openapi: 3.1.0 info: title: Inbound Shipment Management Service version: 2026-08-11.2751322607 description: API for managing inbound shipments and their extra items. servers: - url: https://api-1.test.logitrail.com description: Test / Development Server - url: https://api-1.logitrail.com description: Production Server paths: /v1/inbound-shipments: get: summary: List Inbound Shipments description: Lists inbound shipments, optionally filtered by merchant, status, the `quick_filter=open` group shortcut, the merchant's reference (`merchants_ref`), a creation-date range (`created_at_min`/`created_at_max`), an estimated-arrival-date range (`estimated_arrival_date_min`/`estimated_arrival_date_max`), an originating order via `original_order_id`, a contained product via `has_product_id`, a carrier tracking code via `carrier_tracking_code`, or a free-form `q` search across sender name, merchants_ref, and Logitrail ID. operationId: ListInboundShipments security: - idp: - inbound_shipments:read parameters: - in: query name: merchant schema: description: Owning merchant example: testmerchant.logitrail.com type: string description: Owning merchant - in: query name: status schema: type: string enum: - initial - confirmed - en_route - arrived_at_warehouse - processed - processing - problem - cancelled - deleted title: Status of the inbound shipment. description: The current status of the inbound shipment. This is a read-only property. - in: query name: q schema: description: Free-form single-field search. Matches our_id and merchants_ref as case-insensitive prefixes; matches sender_name as a case-insensitive substring when the query is at least 3 characters long. example: Acme type: string minLength: 1 description: Free-form single-field search. Matches our_id and merchants_ref as case-insensitive prefixes; matches sender_name as a case-insensitive substring when the query is at least 3 characters long. - in: query name: merchants_ref schema: description: Filter by the merchant's reference (exact match) on the inbound shipment. example: PO-2026-001 type: string minLength: 1 description: Filter by the merchant's reference (exact match) on the inbound shipment. - in: query name: created_at_min schema: description: Inclusive lower bound on the inbound shipment creation timestamp. Accepts YYYY-MM-DD (interpreted as start-of-day UTC) or a full ISO 8601 datetime. example: 2026-04-01 anyOf: - type: string format: date 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])))$ - 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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: Inclusive lower bound on the inbound shipment creation timestamp. Accepts YYYY-MM-DD (interpreted as start-of-day UTC) or a full ISO 8601 datetime. - in: query name: created_at_max schema: description: Inclusive upper bound on the inbound shipment creation timestamp. Accepts YYYY-MM-DD (interpreted as end-of-day UTC) or a full ISO 8601 datetime. example: 2026-04-30T23:59:59Z anyOf: - type: string format: date 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])))$ - 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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: Inclusive upper bound on the inbound shipment creation timestamp. Accepts YYYY-MM-DD (interpreted as end-of-day UTC) or a full ISO 8601 datetime. - in: query name: estimated_arrival_date_min schema: description: Inclusive lower bound on the inbound shipment `estimated_arrival_date` (YYYY-MM-DD). Shipments whose `estimated_arrival_date` is null are excluded when this bound is supplied. example: 2026-05-01 type: string format: date 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])))$ description: Inclusive lower bound on the inbound shipment `estimated_arrival_date` (YYYY-MM-DD). Shipments whose `estimated_arrival_date` is null are excluded when this bound is supplied. - in: query name: estimated_arrival_date_max schema: description: Inclusive upper bound on the inbound shipment `estimated_arrival_date` (YYYY-MM-DD). Shipments whose `estimated_arrival_date` is null are excluded when this bound is supplied. example: 2026-05-31 type: string format: date 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])))$ description: Inclusive upper bound on the inbound shipment `estimated_arrival_date` (YYYY-MM-DD). Shipments whose `estimated_arrival_date` is null are excluded when this bound is supplied. - in: query name: original_order_id schema: description: Returns only shipments where at least one line item references the given order via `items[].original_order.id`. 24-character hex MongoDB ObjectId. Useful for finding the order-return inbound shipment(s) that arose from a specific customer order. example: 6585aa3e6629101641191794 type: string pattern: ^[a-f0-9]{24}$ description: Returns only shipments where at least one line item references the given order via `items[].original_order.id`. 24-character hex MongoDB ObjectId. Useful for finding the order-return inbound shipment(s) that arose from a specific customer order. - in: query name: has_product_id schema: description: Returns only shipments where at least one line item references the given product via `items[].product.id`. 24-character hex MongoDB ObjectId. Mirrors the `has_product_id` filter on `ListOrders`. example: 662a66fac1a9fa33f20f9702 type: string pattern: ^[a-f0-9]{24}$ description: Returns only shipments where at least one line item references the given product via `items[].product.id`. 24-character hex MongoDB ObjectId. Mirrors the `has_product_id` filter on `ListOrders`. - in: query name: warehouse_id schema: description: Returns only shipments whose merchant is assigned to the given Warehouse (Merchant.wh). Resolved via a Merchant lookup — a warehouse with no merchants assigned returns no results. 24-character hex MongoDB ObjectId. example: 662a66fac1a9fa33f20f9702 type: string pattern: ^[a-f0-9]{24}$ description: Returns only shipments whose merchant is assigned to the given Warehouse (Merchant.wh). Resolved via a Merchant lookup — a warehouse with no merchants assigned returns no results. 24-character hex MongoDB ObjectId. - in: query name: quick_filter schema: description: Status group shortcut. `open` matches shipments in initial, confirmed, processing, arrived_at_warehouse, or problem status. Ignored when `status` is also given. example: open type: string enum: - open description: Status group shortcut. `open` matches shipments in initial, confirmed, processing, arrived_at_warehouse, or problem status. Ignored when `status` is also given. - in: query name: carrier_tracking_code schema: description: Return only shipments where `carrier_tracking_codes` contains this exact code. example: 1Z999AA10123456784 type: string minLength: 1 description: Return only shipments where `carrier_tracking_codes` contains this exact code. - in: query name: limit schema: default: 250 type: number minimum: 1 maximum: 1000 responses: "200": description: Inbound shipments matching the filters. content: application/json: schema: type: object properties: inbound_shipments: type: array items: type: object properties: merchants_ref: anyOf: - type: string - type: "null" description: Merchant's reference to the inbound shipment. Note that value is trimmed (trailing and leading spaces removed) and empty string is ignored. sender_name: anyOf: - type: string - type: "null" description: Sender's name, as given by the merchant. priority: anyOf: - type: number minimum: -10000000 maximum: 10000000 - type: "null" description: Merchant's priority of the inbound shipment. This can be an integer between -10000000 (slowest handling) to 1000000 (fastest handling). Note that the value is effective only within merchant's other inbound shipments. Value 0 is ignored. merchant_remarks: anyOf: - type: string - type: "null" description: Free text remarks from Merchant to Logitrail. estimated_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Estimated arrival date of the inbound shipment. carrier_tracking_codes: description: Carrier tracking codes for this shipment as provided by the merchant (e.g. parcel label barcodes from the carrier). Used to identify arriving parcels at the warehouse by scanning the label. Pass an empty array to clear all codes. type: array items: type: string minLength: 1 id: type: string pattern: ^[a-f0-9]{24}$ example: 5f8d0f8d8f8d8f8d8f8d8f8d description: Inbound Shipment ID status: type: string enum: - initial - confirmed - en_route - arrived_at_warehouse - processed - processing - problem - cancelled - deleted title: Status of the inbound shipment. description: The current status of the inbound shipment. This is a read-only property. merchant: type: string created: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false our_id: anyOf: - type: string pattern: ^[A-Z0-9]+$ description: Logitrail's inbound shipment identifier. - type: "null" type: anyOf: - type: string enum: - purchase_order - order_return description: Type of the inbound shipment. - type: "null" items: type: array items: type: object properties: item_id: description: Inbound Shipment Item ID type: string pattern: ^[a-f0-9]{24}$ product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product sku: type: string minLength: 1 description: SKU of the product gtin: description: GTIN (Barcode / EAN) of the product, if any type: string minLength: 1 name: type: string minLength: 1 description: Name of the product 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). required: - sku - name additionalProperties: false quantity: type: number minimum: 0 description: Expected quantity to arrive. Can be 0 if the merchant agreed to a line where nothing arrived (see `agreed_amount_stamp`). unit_purchase_price: anyOf: - type: number - type: "null" description: Declared purchase price per unit for this line item. Null when not set. currency: anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Null when not set. stocked_quantity: type: integer minimum: 0 maximum: 9007199254740991 description: Number of units of this product that have been received into the warehouse and assigned to an arrival batch. Includes units that subsequently moved on (picked, sent_out) or were flagged as incidents — those still arrived. Equals the sum of stocked_batches[].quantity. Zero when nothing has arrived yet for this line item. stocked_batches: type: array items: type: object properties: arrival_batch_id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Internal Logitrail identifier of the stocked arrival batch row. Stable across requests but not part of any other public API; treat as opaque. batch_number: anyOf: - type: string - type: "null" description: Batch number recorded at receiving for this stocked entry, if any. Null when the warehouse stored the units without a batch number. best_before_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Best-before / expiration date for this stocked entry, if recorded. quantity: type: integer minimum: 1 maximum: 9007199254740991 description: Number of units of this product stocked (and possibly moved on — picked / sent_out / incident — see DEV-708 semantics) tied to this arrival batch. first_seen_at: anyOf: - 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))$ - type: "null" description: Best-effort ISO 8601 timestamp of the earliest inbound_shipment.to_shelf movement linked to any article in this batch. Null when no such movement is linked to the batch (DEV-709 will replace this with a real ProductArrivalBatch.createdAt column). stocked_location: anyOf: - type: string - type: "null" description: Warehouse location into which the earliest inbound_shipment.to_shelf movement (the one whose timestamp is reported in first_seen_at) placed the goods. Informational; subsequent relocations are not reflected here. Null when first_seen_at is null. required: - arrival_batch_id - batch_number - best_before_date - quantity - first_seen_at - stocked_location additionalProperties: false description: Per-arrival-batch breakdown of the stocked quantity, grouped by ProductArrivalBatch and sorted by arrival_batch_id ascending. Empty when nothing has arrived yet. extra_services: description: LogitrailService attachments recorded against this line item. Public read returns active attachments only; archived ones are visible on internal-audience endpoints. Empty array when no attachments exist for the line. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false original_order: description: "For order-return inbound shipments: reference to the original order from which this returned line originated. Always belongs to the same merchant as the inbound shipment. Null when the line is not tied to an originating order." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id additionalProperties: false - type: "null" agreed_amount_stamp: description: Present when the merchant has agreed to the actually-stocked quantity for this under-delivered line (DEV-2102, via `_agree_amount`). Once set, `quantity` reflects the agreed amount and cannot be changed again through that action. Null when no agreement has been made. anyOf: - type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string from: type: number description: Originally expected quantity for this line before the merchant agreed to the stocked amount. to: type: number description: Quantity the merchant agreed to. Matches `quantity` on this line from this point on. required: - ts - from - to additionalProperties: false - type: "null" required: - product - quantity - unit_purchase_price - currency - stocked_quantity - stocked_batches additionalProperties: false description: List of product items to be expected to arrive in this inbound shipment. extra_items: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Inbound Shipment Extra Item ID item_details: type: object properties: title: type: string gtin: anyOf: - type: string - type: "null" title: GTIN if available description: GTIN (Barcode / EAN) of the extra item product, if it can be clearly identified. required: - title additionalProperties: false reason_code: type: string enum: - exp_date - broken - extra_items - unknown - not_ordered title: Reason Code (why extra item) description: Reason code set by Logitrail warehouse employee. Describes why this extra item is an extra item. quantity: anyOf: - type: number minimum: 1 - type: "null" description: Amount of extra items arrived. remarks: title: Free-form additional info for this extra-item row description: Free-form additional information recorded against the extra-item row by Logitrail warehouse staff. Surfaced to merchants alongside the row. Null when no remarks have been recorded. anyOf: - type: string - type: "null" merchants_decision: anyOf: - type: object properties: code: type: string enum: - already_corrected - stock_as_is - destroy - return_to_sender - other title: Handling instruction code for Logitrail description: Handling instruction code for Logitrail by the Merchant for the extra item. `stock_as_is` folds the item into the shipment automatically; `already_corrected` means the merchant already resolved the discrepancy themselves through another channel and no automation happens. merchant_remarks: title: Other remarks from the merchant to Logitrail description: Free-form instructions/remarks from the merchant to Logitrail. Optional for every code, including other. type: string product: title: Selected product for Stock as-is description: Reference to the merchant's catalog product this extra item was decided to be stocked as. Present only when code is stock_as_is. type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product required: - id additionalProperties: false decision_stamp: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false required: - code - decision_stamp additionalProperties: false - type: "null" required: - id - item_details - reason_code additionalProperties: false description: List of extra items that do not match any product or item in the inbound shipment. actual_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Actual arrival date of the inbound shipment. extra_services: description: LogitrailService attachments on this inbound shipment. Only active attachments are returned. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false warehouse: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: The shipment's fulfilling warehouse, resolved from the shipment's merchant's assigned warehouse. Null if the merchant does not resolve or has no warehouse assigned. Available regardless of arrival status. warehouse_location: anyOf: - type: object properties: id: type: string required: - id additionalProperties: false - type: "null" description: Raw arrival location (a WarehouseLocation id, a human-assigned string code, not an ObjectId). Null before the shipment has arrived. order_return: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: "The order return this shipment was created from, if any. Only set for type: order_return shipments, created when a merchant releases a to_shelf/resend_as_new decision for processing." required: - merchants_ref - sender_name - priority - merchant_remarks - estimated_arrival_date - id - status - merchant - created - type - items - extra_items - actual_arrival_date - warehouse - warehouse_location - order_return additionalProperties: false description: Inbound Shipment Data required: - inbound_shipments 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 Inbound Shipment description: Creates a new inbound shipment in the `initial` status for the merchant. operationId: CreateInboundShipment security: - idp: - inbound_shipments: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: inbound_shipment: type: object properties: merchants_ref: anyOf: - type: string - type: "null" description: Merchant's reference to the inbound shipment. Note that value is trimmed (trailing and leading spaces removed) and empty string is ignored. sender_name: anyOf: - type: string - type: "null" description: Sender's name, as given by the merchant. priority: anyOf: - type: number minimum: -10000000 maximum: 10000000 - type: "null" description: Merchant's priority of the inbound shipment. This can be an integer between -10000000 (slowest handling) to 1000000 (fastest handling). Note that the value is effective only within merchant's other inbound shipments. Value 0 is ignored. merchant_remarks: anyOf: - type: string - type: "null" description: Free text remarks from Merchant to Logitrail. estimated_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Estimated arrival date of the inbound shipment. carrier_tracking_codes: description: Carrier tracking codes for this shipment as provided by the merchant (e.g. parcel label barcodes from the carrier). Used to identify arriving parcels at the warehouse by scanning the label. Pass an empty array to clear all codes. type: array items: type: string minLength: 1 type: default: purchase_order type: string enum: - purchase_order - order_return description: Type of the inbound shipment. items: default: [] description: List of product items to be expected to arrive in this inbound shipment. type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail technical ID of the product. Provide exactly one of id or sku. sku: type: string minLength: 1 description: Merchant's SKU of the product. Resolved server-side to an active product owned by the requesting merchant. Provide exactly one of id or sku. vendor_skus: description: Optional product-profile update. When set, the referenced product's vendor_skus array is replaced with this value as a side-effect of the inbound-shipment write. Omit to leave the profile untouched; pass an empty array to clear it. 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 quantity: type: number minimum: 1 description: Expected quantity to arrive unit_purchase_price: description: Declared purchase price per unit for this line item. Optional. Pass null to clear an existing value. anyOf: - type: number - type: "null" currency: description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR", "USD"). Optional. Pass null to clear. anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" original_order: description: "For order-return inbound shipments: reference to the original order from which the returned product originated. Must belong to the requesting merchant. Pass null to clear an existing reference; omit to leave it unchanged." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id - type: "null" required: - product - quantity description: Inbound Shipment Data for Creation required: - inbound_shipment responses: "201": description: Newly created inbound shipment. content: application/json: schema: type: object properties: inbound_shipment: type: object properties: merchants_ref: anyOf: - type: string - type: "null" description: Merchant's reference to the inbound shipment. Note that value is trimmed (trailing and leading spaces removed) and empty string is ignored. sender_name: anyOf: - type: string - type: "null" description: Sender's name, as given by the merchant. priority: anyOf: - type: number minimum: -10000000 maximum: 10000000 - type: "null" description: Merchant's priority of the inbound shipment. This can be an integer between -10000000 (slowest handling) to 1000000 (fastest handling). Note that the value is effective only within merchant's other inbound shipments. Value 0 is ignored. merchant_remarks: anyOf: - type: string - type: "null" description: Free text remarks from Merchant to Logitrail. estimated_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Estimated arrival date of the inbound shipment. carrier_tracking_codes: description: Carrier tracking codes for this shipment as provided by the merchant (e.g. parcel label barcodes from the carrier). Used to identify arriving parcels at the warehouse by scanning the label. Pass an empty array to clear all codes. type: array items: type: string minLength: 1 id: type: string pattern: ^[a-f0-9]{24}$ example: 5f8d0f8d8f8d8f8d8f8d8f8d description: Inbound Shipment ID status: type: string enum: - initial - confirmed - en_route - arrived_at_warehouse - processed - processing - problem - cancelled - deleted title: Status of the inbound shipment. description: The current status of the inbound shipment. This is a read-only property. merchant: type: string created: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false our_id: anyOf: - type: string pattern: ^[A-Z0-9]+$ description: Logitrail's inbound shipment identifier. - type: "null" type: anyOf: - type: string enum: - purchase_order - order_return description: Type of the inbound shipment. - type: "null" items: type: array items: type: object properties: item_id: description: Inbound Shipment Item ID type: string pattern: ^[a-f0-9]{24}$ product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product sku: type: string minLength: 1 description: SKU of the product gtin: description: GTIN (Barcode / EAN) of the product, if any type: string minLength: 1 name: type: string minLength: 1 description: Name of the product 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). required: - sku - name additionalProperties: false quantity: type: number minimum: 0 description: Expected quantity to arrive. Can be 0 if the merchant agreed to a line where nothing arrived (see `agreed_amount_stamp`). unit_purchase_price: anyOf: - type: number - type: "null" description: Declared purchase price per unit for this line item. Null when not set. currency: anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Null when not set. stocked_quantity: type: integer minimum: 0 maximum: 9007199254740991 description: Number of units of this product that have been received into the warehouse and assigned to an arrival batch. Includes units that subsequently moved on (picked, sent_out) or were flagged as incidents — those still arrived. Equals the sum of stocked_batches[].quantity. Zero when nothing has arrived yet for this line item. stocked_batches: type: array items: type: object properties: arrival_batch_id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Internal Logitrail identifier of the stocked arrival batch row. Stable across requests but not part of any other public API; treat as opaque. batch_number: anyOf: - type: string - type: "null" description: Batch number recorded at receiving for this stocked entry, if any. Null when the warehouse stored the units without a batch number. best_before_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Best-before / expiration date for this stocked entry, if recorded. quantity: type: integer minimum: 1 maximum: 9007199254740991 description: Number of units of this product stocked (and possibly moved on — picked / sent_out / incident — see DEV-708 semantics) tied to this arrival batch. first_seen_at: anyOf: - 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))$ - type: "null" description: Best-effort ISO 8601 timestamp of the earliest inbound_shipment.to_shelf movement linked to any article in this batch. Null when no such movement is linked to the batch (DEV-709 will replace this with a real ProductArrivalBatch.createdAt column). stocked_location: anyOf: - type: string - type: "null" description: Warehouse location into which the earliest inbound_shipment.to_shelf movement (the one whose timestamp is reported in first_seen_at) placed the goods. Informational; subsequent relocations are not reflected here. Null when first_seen_at is null. required: - arrival_batch_id - batch_number - best_before_date - quantity - first_seen_at - stocked_location additionalProperties: false description: Per-arrival-batch breakdown of the stocked quantity, grouped by ProductArrivalBatch and sorted by arrival_batch_id ascending. Empty when nothing has arrived yet. extra_services: description: LogitrailService attachments recorded against this line item. Public read returns active attachments only; archived ones are visible on internal-audience endpoints. Empty array when no attachments exist for the line. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false original_order: description: "For order-return inbound shipments: reference to the original order from which this returned line originated. Always belongs to the same merchant as the inbound shipment. Null when the line is not tied to an originating order." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id additionalProperties: false - type: "null" agreed_amount_stamp: description: Present when the merchant has agreed to the actually-stocked quantity for this under-delivered line (DEV-2102, via `_agree_amount`). Once set, `quantity` reflects the agreed amount and cannot be changed again through that action. Null when no agreement has been made. anyOf: - type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string from: type: number description: Originally expected quantity for this line before the merchant agreed to the stocked amount. to: type: number description: Quantity the merchant agreed to. Matches `quantity` on this line from this point on. required: - ts - from - to additionalProperties: false - type: "null" required: - product - quantity - unit_purchase_price - currency - stocked_quantity - stocked_batches additionalProperties: false description: List of product items to be expected to arrive in this inbound shipment. extra_items: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Inbound Shipment Extra Item ID item_details: type: object properties: title: type: string gtin: anyOf: - type: string - type: "null" title: GTIN if available description: GTIN (Barcode / EAN) of the extra item product, if it can be clearly identified. required: - title additionalProperties: false reason_code: type: string enum: - exp_date - broken - extra_items - unknown - not_ordered title: Reason Code (why extra item) description: Reason code set by Logitrail warehouse employee. Describes why this extra item is an extra item. quantity: anyOf: - type: number minimum: 1 - type: "null" description: Amount of extra items arrived. remarks: title: Free-form additional info for this extra-item row description: Free-form additional information recorded against the extra-item row by Logitrail warehouse staff. Surfaced to merchants alongside the row. Null when no remarks have been recorded. anyOf: - type: string - type: "null" merchants_decision: anyOf: - type: object properties: code: type: string enum: - already_corrected - stock_as_is - destroy - return_to_sender - other title: Handling instruction code for Logitrail description: Handling instruction code for Logitrail by the Merchant for the extra item. `stock_as_is` folds the item into the shipment automatically; `already_corrected` means the merchant already resolved the discrepancy themselves through another channel and no automation happens. merchant_remarks: title: Other remarks from the merchant to Logitrail description: Free-form instructions/remarks from the merchant to Logitrail. Optional for every code, including other. type: string product: title: Selected product for Stock as-is description: Reference to the merchant's catalog product this extra item was decided to be stocked as. Present only when code is stock_as_is. type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product required: - id additionalProperties: false decision_stamp: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false required: - code - decision_stamp additionalProperties: false - type: "null" required: - id - item_details - reason_code additionalProperties: false description: List of extra items that do not match any product or item in the inbound shipment. actual_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Actual arrival date of the inbound shipment. extra_services: description: LogitrailService attachments on this inbound shipment. Only active attachments are returned. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false warehouse: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: The shipment's fulfilling warehouse, resolved from the shipment's merchant's assigned warehouse. Null if the merchant does not resolve or has no warehouse assigned. Available regardless of arrival status. warehouse_location: anyOf: - type: object properties: id: type: string required: - id additionalProperties: false - type: "null" description: Raw arrival location (a WarehouseLocation id, a human-assigned string code, not an ObjectId). Null before the shipment has arrived. order_return: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: "The order return this shipment was created from, if any. Only set for type: order_return shipments, created when a merchant releases a to_shelf/resend_as_new decision for processing." required: - merchants_ref - sender_name - priority - merchant_remarks - estimated_arrival_date - id - status - merchant - created - type - items - extra_items - actual_arrival_date - warehouse - warehouse_location - order_return additionalProperties: false description: Inbound Shipment Data required: - inbound_shipment 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 "500": description: Internal error while persisting the new shipment. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. /v1/inbound-shipments/statistics: get: summary: Get Inbound Shipment Statistics description: Returns per-status counts of the merchant inbound shipments. operationId: GetInboundStatistics security: - idp: - inbound_shipments: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: Statistics for the merchant. content: application/json: schema: type: object properties: inbound_shipment_statistics: type: object properties: initial_count: default: 0 type: number minimum: 0 confirmed_count: default: 0 type: number minimum: 0 arrived_count: default: 0 type: number minimum: 0 problem_count: default: 0 type: number minimum: 0 processing_count: default: 0 type: number minimum: 0 required: - initial_count - confirmed_count - arrived_count - problem_count - processing_count additionalProperties: false required: - inbound_shipment_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/inbound-shipments/statistics/kpis: get: summary: Get Inbound Shipment Statistics KPIs description: Returns aggregated inbound-shipment KPIs for the authenticated merchant, with flexible grouping and date filtering. Group by `created_at_date` and/or `arrived_at_date` to build created-per-day and arrived-per-day timelines, optionally split by `status`. The only KPI today is `shipment_count`. Filter by creation timestamp (`created_at_min`/`created_at_max`), actual-arrival date (`arrived_at_min`/`arrived_at_max`), and/or `status`. operationId: GetInboundStatisticsKpis security: - idp: - inbound_shipments: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: created_at_min schema: description: Minimum shipment creation timestamp (inclusive). ISO 8601 datetime or date (YYYY-MM-DD). Date without time defaults to 00:00:00.000Z. example: 2026-04-01 type: string description: Minimum shipment creation timestamp (inclusive). ISO 8601 datetime or date (YYYY-MM-DD). Date without time defaults to 00:00:00.000Z. - in: query name: created_at_max schema: description: Maximum shipment creation timestamp (inclusive). ISO 8601 datetime or date (YYYY-MM-DD). Date without time defaults to 23:59:59.999Z. example: 2026-04-30T23:59:59Z type: string description: Maximum shipment creation timestamp (inclusive). ISO 8601 datetime or date (YYYY-MM-DD). Date without time defaults to 23:59:59.999Z. - in: query name: arrived_at_min schema: description: Minimum actual-arrival date (inclusive), YYYY-MM-DD. Shipments that have not arrived (no actual arrival date) are excluded when this bound is supplied. example: 2026-04-01 type: string format: date 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])))$ description: Minimum actual-arrival date (inclusive), YYYY-MM-DD. Shipments that have not arrived (no actual arrival date) are excluded when this bound is supplied. - in: query name: arrived_at_max schema: description: Maximum actual-arrival date (inclusive), YYYY-MM-DD. Shipments that have not arrived (no actual arrival date) are excluded when this bound is supplied. example: 2026-04-30 type: string format: date 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])))$ description: Maximum actual-arrival date (inclusive), YYYY-MM-DD. Shipments that have not arrived (no actual arrival date) are excluded when this bound is supplied. - in: query name: status schema: description: Comma-separated list of shipment statuses to filter by (e.g. "confirmed,arrived_at_warehouse"). type: string description: Comma-separated list of shipment statuses to filter by (e.g. "confirmed,arrived_at_warehouse"). - in: query name: kpis schema: description: "Comma-separated KPIs to compute. Allowed: shipment_count. Default: shipment_count." type: string description: "Comma-separated KPIs to compute. Allowed: shipment_count. Default: shipment_count." - in: query name: group_by schema: description: "Comma-separated dimensions to group by. Allowed: status, created_at_date, arrived_at_date." type: string description: "Comma-separated dimensions to group by. Allowed: status, created_at_date, arrived_at_date." responses: "200": description: Aggregated inbound-shipment KPIs for the merchant. content: application/json: schema: type: object properties: inbound_shipment_statistics_kpis: type: object properties: query: type: object properties: created_at_min: type: string created_at_max: type: string arrived_at_min: type: string arrived_at_max: type: string status: type: array items: type: string merchant: type: string group_by: type: array items: type: string kpis: type: array items: type: string required: - group_by - kpis additionalProperties: false description: Echo of the parsed query parameters. results: type: array items: type: object properties: dimensions: type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: number - type: "null" description: Dimension values for this result row, keyed by the requested group_by dimensions (e.g. status, created_at_date, arrived_at_date). A null value means the shipment has no value for that dimension (e.g. it has not arrived yet). kpis: type: object propertyNames: type: string additionalProperties: type: number description: KPI name to numeric value mapping (e.g. shipment_count). required: - dimensions - kpis additionalProperties: false description: Aggregation result rows, one per dimension combination. totals: type: object properties: kpis: type: object propertyNames: type: string additionalProperties: type: number description: KPI name to numeric value mapping (e.g. shipment_count). required: - kpis additionalProperties: false description: Aggregate totals across all result rows. required: - query - results - totals additionalProperties: false required: - inbound_shipment_statistics_kpis 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/inbound-shipments/product-arrival-estimation/{productId}: get: summary: Get Product Arrival Estimations description: Returns arrival estimations for a single product across open inbound shipments of the merchant. operationId: GetProductArrivalEstimations security: - idp: - inbound_shipments: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: Arrival estimations for the product. content: application/json: schema: type: object properties: arrival_estimations: type: array items: type: object properties: product: type: object properties: id: type: string required: - id additionalProperties: false inbound_shipment: type: object properties: id: type: string estimated_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" sender_name: anyOf: - type: string - type: "null" required: - id - estimated_arrival_date - sender_name additionalProperties: false estimated_on_shelf_at: anyOf: - 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))$ - type: "null" arriving_amount: type: number required: - product - inbound_shipment - estimated_on_shelf_at - arriving_amount additionalProperties: false required: - arrival_estimations 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/inbound-shipments/{inboundShipmentId}: get: summary: Get Inbound Shipment description: Returns the full DTO of a single inbound shipment. operationId: GetInboundShipment security: - idp: - inbound_shipments:read parameters: [] responses: "200": description: The requested inbound shipment. content: application/json: schema: type: object properties: inbound_shipment: type: object properties: merchants_ref: anyOf: - type: string - type: "null" description: Merchant's reference to the inbound shipment. Note that value is trimmed (trailing and leading spaces removed) and empty string is ignored. sender_name: anyOf: - type: string - type: "null" description: Sender's name, as given by the merchant. priority: anyOf: - type: number minimum: -10000000 maximum: 10000000 - type: "null" description: Merchant's priority of the inbound shipment. This can be an integer between -10000000 (slowest handling) to 1000000 (fastest handling). Note that the value is effective only within merchant's other inbound shipments. Value 0 is ignored. merchant_remarks: anyOf: - type: string - type: "null" description: Free text remarks from Merchant to Logitrail. estimated_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Estimated arrival date of the inbound shipment. carrier_tracking_codes: description: Carrier tracking codes for this shipment as provided by the merchant (e.g. parcel label barcodes from the carrier). Used to identify arriving parcels at the warehouse by scanning the label. Pass an empty array to clear all codes. type: array items: type: string minLength: 1 id: type: string pattern: ^[a-f0-9]{24}$ example: 5f8d0f8d8f8d8f8d8f8d8f8d description: Inbound Shipment ID status: type: string enum: - initial - confirmed - en_route - arrived_at_warehouse - processed - processing - problem - cancelled - deleted title: Status of the inbound shipment. description: The current status of the inbound shipment. This is a read-only property. merchant: type: string created: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false our_id: anyOf: - type: string pattern: ^[A-Z0-9]+$ description: Logitrail's inbound shipment identifier. - type: "null" type: anyOf: - type: string enum: - purchase_order - order_return description: Type of the inbound shipment. - type: "null" items: type: array items: type: object properties: item_id: description: Inbound Shipment Item ID type: string pattern: ^[a-f0-9]{24}$ product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product sku: type: string minLength: 1 description: SKU of the product gtin: description: GTIN (Barcode / EAN) of the product, if any type: string minLength: 1 name: type: string minLength: 1 description: Name of the product 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). required: - sku - name additionalProperties: false quantity: type: number minimum: 0 description: Expected quantity to arrive. Can be 0 if the merchant agreed to a line where nothing arrived (see `agreed_amount_stamp`). unit_purchase_price: anyOf: - type: number - type: "null" description: Declared purchase price per unit for this line item. Null when not set. currency: anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Null when not set. stocked_quantity: type: integer minimum: 0 maximum: 9007199254740991 description: Number of units of this product that have been received into the warehouse and assigned to an arrival batch. Includes units that subsequently moved on (picked, sent_out) or were flagged as incidents — those still arrived. Equals the sum of stocked_batches[].quantity. Zero when nothing has arrived yet for this line item. stocked_batches: type: array items: type: object properties: arrival_batch_id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Internal Logitrail identifier of the stocked arrival batch row. Stable across requests but not part of any other public API; treat as opaque. batch_number: anyOf: - type: string - type: "null" description: Batch number recorded at receiving for this stocked entry, if any. Null when the warehouse stored the units without a batch number. best_before_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Best-before / expiration date for this stocked entry, if recorded. quantity: type: integer minimum: 1 maximum: 9007199254740991 description: Number of units of this product stocked (and possibly moved on — picked / sent_out / incident — see DEV-708 semantics) tied to this arrival batch. first_seen_at: anyOf: - 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))$ - type: "null" description: Best-effort ISO 8601 timestamp of the earliest inbound_shipment.to_shelf movement linked to any article in this batch. Null when no such movement is linked to the batch (DEV-709 will replace this with a real ProductArrivalBatch.createdAt column). stocked_location: anyOf: - type: string - type: "null" description: Warehouse location into which the earliest inbound_shipment.to_shelf movement (the one whose timestamp is reported in first_seen_at) placed the goods. Informational; subsequent relocations are not reflected here. Null when first_seen_at is null. required: - arrival_batch_id - batch_number - best_before_date - quantity - first_seen_at - stocked_location additionalProperties: false description: Per-arrival-batch breakdown of the stocked quantity, grouped by ProductArrivalBatch and sorted by arrival_batch_id ascending. Empty when nothing has arrived yet. extra_services: description: LogitrailService attachments recorded against this line item. Public read returns active attachments only; archived ones are visible on internal-audience endpoints. Empty array when no attachments exist for the line. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false original_order: description: "For order-return inbound shipments: reference to the original order from which this returned line originated. Always belongs to the same merchant as the inbound shipment. Null when the line is not tied to an originating order." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id additionalProperties: false - type: "null" agreed_amount_stamp: description: Present when the merchant has agreed to the actually-stocked quantity for this under-delivered line (DEV-2102, via `_agree_amount`). Once set, `quantity` reflects the agreed amount and cannot be changed again through that action. Null when no agreement has been made. anyOf: - type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string from: type: number description: Originally expected quantity for this line before the merchant agreed to the stocked amount. to: type: number description: Quantity the merchant agreed to. Matches `quantity` on this line from this point on. required: - ts - from - to additionalProperties: false - type: "null" required: - product - quantity - unit_purchase_price - currency - stocked_quantity - stocked_batches additionalProperties: false description: List of product items to be expected to arrive in this inbound shipment. extra_items: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Inbound Shipment Extra Item ID item_details: type: object properties: title: type: string gtin: anyOf: - type: string - type: "null" title: GTIN if available description: GTIN (Barcode / EAN) of the extra item product, if it can be clearly identified. required: - title additionalProperties: false reason_code: type: string enum: - exp_date - broken - extra_items - unknown - not_ordered title: Reason Code (why extra item) description: Reason code set by Logitrail warehouse employee. Describes why this extra item is an extra item. quantity: anyOf: - type: number minimum: 1 - type: "null" description: Amount of extra items arrived. remarks: title: Free-form additional info for this extra-item row description: Free-form additional information recorded against the extra-item row by Logitrail warehouse staff. Surfaced to merchants alongside the row. Null when no remarks have been recorded. anyOf: - type: string - type: "null" merchants_decision: anyOf: - type: object properties: code: type: string enum: - already_corrected - stock_as_is - destroy - return_to_sender - other title: Handling instruction code for Logitrail description: Handling instruction code for Logitrail by the Merchant for the extra item. `stock_as_is` folds the item into the shipment automatically; `already_corrected` means the merchant already resolved the discrepancy themselves through another channel and no automation happens. merchant_remarks: title: Other remarks from the merchant to Logitrail description: Free-form instructions/remarks from the merchant to Logitrail. Optional for every code, including other. type: string product: title: Selected product for Stock as-is description: Reference to the merchant's catalog product this extra item was decided to be stocked as. Present only when code is stock_as_is. type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product required: - id additionalProperties: false decision_stamp: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false required: - code - decision_stamp additionalProperties: false - type: "null" required: - id - item_details - reason_code additionalProperties: false description: List of extra items that do not match any product or item in the inbound shipment. actual_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Actual arrival date of the inbound shipment. extra_services: description: LogitrailService attachments on this inbound shipment. Only active attachments are returned. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false warehouse: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: The shipment's fulfilling warehouse, resolved from the shipment's merchant's assigned warehouse. Null if the merchant does not resolve or has no warehouse assigned. Available regardless of arrival status. warehouse_location: anyOf: - type: object properties: id: type: string required: - id additionalProperties: false - type: "null" description: Raw arrival location (a WarehouseLocation id, a human-assigned string code, not an ObjectId). Null before the shipment has arrived. order_return: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: "The order return this shipment was created from, if any. Only set for type: order_return shipments, created when a merchant releases a to_shelf/resend_as_new decision for processing." required: - merchants_ref - sender_name - priority - merchant_remarks - estimated_arrival_date - id - status - merchant - created - type - items - extra_items - actual_arrival_date - warehouse - warehouse_location - order_return additionalProperties: false description: Inbound Shipment Data required: - inbound_shipment 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: Inbound shipment not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. patch: summary: Update Inbound Shipment description: Partially updates an inbound shipment. Only fields present in the request body are modified; omitted fields are left unchanged. Updating `items` replaces the full item list. Editing is allowed while the shipment is in `initial`, `confirmed`, `en_route`, or `problem` — `problem` is an intermediate investigation status, so corrections can still be applied. Returns 409 if the shipment is in a status that no longer allows edits (`arrived_at_warehouse`, `processing`, `processed`, `cancelled`, or `deleted`). operationId: UpdateInboundShipment security: - idp: - inbound_shipments: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: inbound_shipment: type: object properties: merchants_ref: anyOf: - type: string - type: "null" description: Merchant's reference to the inbound shipment. Note that value is trimmed (trailing and leading spaces removed) and empty string is ignored. sender_name: anyOf: - type: string - type: "null" description: Sender's name, as given by the merchant. priority: anyOf: - type: number minimum: -10000000 maximum: 10000000 - type: "null" description: Merchant's priority of the inbound shipment. This can be an integer between -10000000 (slowest handling) to 1000000 (fastest handling). Note that the value is effective only within merchant's other inbound shipments. Value 0 is ignored. merchant_remarks: anyOf: - type: string - type: "null" description: Free text remarks from Merchant to Logitrail. estimated_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Estimated arrival date of the inbound shipment. carrier_tracking_codes: description: Carrier tracking codes for this shipment as provided by the merchant (e.g. parcel label barcodes from the carrier). Used to identify arriving parcels at the warehouse by scanning the label. Pass an empty array to clear all codes. type: array items: type: string minLength: 1 items: type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail technical ID of the product. Provide exactly one of id or sku. sku: type: string minLength: 1 description: Merchant's SKU of the product. Resolved server-side to an active product owned by the requesting merchant. Provide exactly one of id or sku. vendor_skus: description: Optional product-profile update. When set, the referenced product's vendor_skus array is replaced with this value as a side-effect of the inbound-shipment write. Omit to leave the profile untouched; pass an empty array to clear it. 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 quantity: type: number minimum: 1 description: Expected quantity to arrive unit_purchase_price: description: Declared purchase price per unit for this line item. Optional. Pass null to clear an existing value. anyOf: - type: number - type: "null" currency: description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR", "USD"). Optional. Pass null to clear. anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" original_order: description: "For order-return inbound shipments: reference to the original order from which the returned product originated. Must belong to the requesting merchant. Pass null to clear an existing reference; omit to leave it unchanged." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id - type: "null" required: - product - quantity description: List of product items to be expected to arrive in this inbound shipment. Note that passing this argument *replaces* the item list. If you want to add or remove individual item, use /products endpoint. description: Inbound Shipment Data for Update required: - inbound_shipment responses: "200": description: The updated inbound shipment. content: application/json: schema: type: object properties: inbound_shipment: type: object properties: merchants_ref: anyOf: - type: string - type: "null" description: Merchant's reference to the inbound shipment. Note that value is trimmed (trailing and leading spaces removed) and empty string is ignored. sender_name: anyOf: - type: string - type: "null" description: Sender's name, as given by the merchant. priority: anyOf: - type: number minimum: -10000000 maximum: 10000000 - type: "null" description: Merchant's priority of the inbound shipment. This can be an integer between -10000000 (slowest handling) to 1000000 (fastest handling). Note that the value is effective only within merchant's other inbound shipments. Value 0 is ignored. merchant_remarks: anyOf: - type: string - type: "null" description: Free text remarks from Merchant to Logitrail. estimated_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Estimated arrival date of the inbound shipment. carrier_tracking_codes: description: Carrier tracking codes for this shipment as provided by the merchant (e.g. parcel label barcodes from the carrier). Used to identify arriving parcels at the warehouse by scanning the label. Pass an empty array to clear all codes. type: array items: type: string minLength: 1 id: type: string pattern: ^[a-f0-9]{24}$ example: 5f8d0f8d8f8d8f8d8f8d8f8d description: Inbound Shipment ID status: type: string enum: - initial - confirmed - en_route - arrived_at_warehouse - processed - processing - problem - cancelled - deleted title: Status of the inbound shipment. description: The current status of the inbound shipment. This is a read-only property. merchant: type: string created: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false our_id: anyOf: - type: string pattern: ^[A-Z0-9]+$ description: Logitrail's inbound shipment identifier. - type: "null" type: anyOf: - type: string enum: - purchase_order - order_return description: Type of the inbound shipment. - type: "null" items: type: array items: type: object properties: item_id: description: Inbound Shipment Item ID type: string pattern: ^[a-f0-9]{24}$ product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product sku: type: string minLength: 1 description: SKU of the product gtin: description: GTIN (Barcode / EAN) of the product, if any type: string minLength: 1 name: type: string minLength: 1 description: Name of the product 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). required: - sku - name additionalProperties: false quantity: type: number minimum: 0 description: Expected quantity to arrive. Can be 0 if the merchant agreed to a line where nothing arrived (see `agreed_amount_stamp`). unit_purchase_price: anyOf: - type: number - type: "null" description: Declared purchase price per unit for this line item. Null when not set. currency: anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Null when not set. stocked_quantity: type: integer minimum: 0 maximum: 9007199254740991 description: Number of units of this product that have been received into the warehouse and assigned to an arrival batch. Includes units that subsequently moved on (picked, sent_out) or were flagged as incidents — those still arrived. Equals the sum of stocked_batches[].quantity. Zero when nothing has arrived yet for this line item. stocked_batches: type: array items: type: object properties: arrival_batch_id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Internal Logitrail identifier of the stocked arrival batch row. Stable across requests but not part of any other public API; treat as opaque. batch_number: anyOf: - type: string - type: "null" description: Batch number recorded at receiving for this stocked entry, if any. Null when the warehouse stored the units without a batch number. best_before_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Best-before / expiration date for this stocked entry, if recorded. quantity: type: integer minimum: 1 maximum: 9007199254740991 description: Number of units of this product stocked (and possibly moved on — picked / sent_out / incident — see DEV-708 semantics) tied to this arrival batch. first_seen_at: anyOf: - 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))$ - type: "null" description: Best-effort ISO 8601 timestamp of the earliest inbound_shipment.to_shelf movement linked to any article in this batch. Null when no such movement is linked to the batch (DEV-709 will replace this with a real ProductArrivalBatch.createdAt column). stocked_location: anyOf: - type: string - type: "null" description: Warehouse location into which the earliest inbound_shipment.to_shelf movement (the one whose timestamp is reported in first_seen_at) placed the goods. Informational; subsequent relocations are not reflected here. Null when first_seen_at is null. required: - arrival_batch_id - batch_number - best_before_date - quantity - first_seen_at - stocked_location additionalProperties: false description: Per-arrival-batch breakdown of the stocked quantity, grouped by ProductArrivalBatch and sorted by arrival_batch_id ascending. Empty when nothing has arrived yet. extra_services: description: LogitrailService attachments recorded against this line item. Public read returns active attachments only; archived ones are visible on internal-audience endpoints. Empty array when no attachments exist for the line. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false original_order: description: "For order-return inbound shipments: reference to the original order from which this returned line originated. Always belongs to the same merchant as the inbound shipment. Null when the line is not tied to an originating order." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id additionalProperties: false - type: "null" agreed_amount_stamp: description: Present when the merchant has agreed to the actually-stocked quantity for this under-delivered line (DEV-2102, via `_agree_amount`). Once set, `quantity` reflects the agreed amount and cannot be changed again through that action. Null when no agreement has been made. anyOf: - type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string from: type: number description: Originally expected quantity for this line before the merchant agreed to the stocked amount. to: type: number description: Quantity the merchant agreed to. Matches `quantity` on this line from this point on. required: - ts - from - to additionalProperties: false - type: "null" required: - product - quantity - unit_purchase_price - currency - stocked_quantity - stocked_batches additionalProperties: false description: List of product items to be expected to arrive in this inbound shipment. extra_items: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Inbound Shipment Extra Item ID item_details: type: object properties: title: type: string gtin: anyOf: - type: string - type: "null" title: GTIN if available description: GTIN (Barcode / EAN) of the extra item product, if it can be clearly identified. required: - title additionalProperties: false reason_code: type: string enum: - exp_date - broken - extra_items - unknown - not_ordered title: Reason Code (why extra item) description: Reason code set by Logitrail warehouse employee. Describes why this extra item is an extra item. quantity: anyOf: - type: number minimum: 1 - type: "null" description: Amount of extra items arrived. remarks: title: Free-form additional info for this extra-item row description: Free-form additional information recorded against the extra-item row by Logitrail warehouse staff. Surfaced to merchants alongside the row. Null when no remarks have been recorded. anyOf: - type: string - type: "null" merchants_decision: anyOf: - type: object properties: code: type: string enum: - already_corrected - stock_as_is - destroy - return_to_sender - other title: Handling instruction code for Logitrail description: Handling instruction code for Logitrail by the Merchant for the extra item. `stock_as_is` folds the item into the shipment automatically; `already_corrected` means the merchant already resolved the discrepancy themselves through another channel and no automation happens. merchant_remarks: title: Other remarks from the merchant to Logitrail description: Free-form instructions/remarks from the merchant to Logitrail. Optional for every code, including other. type: string product: title: Selected product for Stock as-is description: Reference to the merchant's catalog product this extra item was decided to be stocked as. Present only when code is stock_as_is. type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product required: - id additionalProperties: false decision_stamp: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false required: - code - decision_stamp additionalProperties: false - type: "null" required: - id - item_details - reason_code additionalProperties: false description: List of extra items that do not match any product or item in the inbound shipment. actual_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Actual arrival date of the inbound shipment. extra_services: description: LogitrailService attachments on this inbound shipment. Only active attachments are returned. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false warehouse: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: The shipment's fulfilling warehouse, resolved from the shipment's merchant's assigned warehouse. Null if the merchant does not resolve or has no warehouse assigned. Available regardless of arrival status. warehouse_location: anyOf: - type: object properties: id: type: string required: - id additionalProperties: false - type: "null" description: Raw arrival location (a WarehouseLocation id, a human-assigned string code, not an ObjectId). Null before the shipment has arrived. order_return: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: "The order return this shipment was created from, if any. Only set for type: order_return shipments, created when a merchant releases a to_shelf/resend_as_new decision for processing." required: - merchants_ref - sender_name - priority - merchant_remarks - estimated_arrival_date - id - status - merchant - created - type - items - extra_items - actual_arrival_date - warehouse - warehouse_location - order_return additionalProperties: false description: Inbound Shipment Data required: - inbound_shipment 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: Inbound shipment not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. "409": description: "Inbound shipment is in a status that does not allow editing (error_code inbound_shipment.edit_not_allowed), or the submitted `items` array conflicts with a line's already-arrived or already-agreed state: a quantity below what has already arrived (inbound_shipment.item_has_arrivals), a changed or omitted amount on an already-agreed line (inbound_shipment.item_amount_already_agreed), or the shipment has more than one existing line for the same product and this endpoint cannot safely tell them apart (inbound_shipment.ambiguous_duplicate_product_lines)." content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. /v1/inbound-shipments/{inboundShipmentId}/_cancel: post: summary: Cancel Inbound Shipment description: Cancels an inbound shipment, transitioning it to the `cancelled` status. Returns 409 if the shipment is already being processed at the warehouse (`arrived_at_warehouse` or `processing` status). operationId: CancelInboundShipment security: - idp: - inbound_shipments: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. responses: "200": description: The cancelled inbound shipment. content: application/json: schema: type: object properties: inbound_shipment: type: object properties: merchants_ref: anyOf: - type: string - type: "null" description: Merchant's reference to the inbound shipment. Note that value is trimmed (trailing and leading spaces removed) and empty string is ignored. sender_name: anyOf: - type: string - type: "null" description: Sender's name, as given by the merchant. priority: anyOf: - type: number minimum: -10000000 maximum: 10000000 - type: "null" description: Merchant's priority of the inbound shipment. This can be an integer between -10000000 (slowest handling) to 1000000 (fastest handling). Note that the value is effective only within merchant's other inbound shipments. Value 0 is ignored. merchant_remarks: anyOf: - type: string - type: "null" description: Free text remarks from Merchant to Logitrail. estimated_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Estimated arrival date of the inbound shipment. carrier_tracking_codes: description: Carrier tracking codes for this shipment as provided by the merchant (e.g. parcel label barcodes from the carrier). Used to identify arriving parcels at the warehouse by scanning the label. Pass an empty array to clear all codes. type: array items: type: string minLength: 1 id: type: string pattern: ^[a-f0-9]{24}$ example: 5f8d0f8d8f8d8f8d8f8d8f8d description: Inbound Shipment ID status: type: string enum: - initial - confirmed - en_route - arrived_at_warehouse - processed - processing - problem - cancelled - deleted title: Status of the inbound shipment. description: The current status of the inbound shipment. This is a read-only property. merchant: type: string created: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false our_id: anyOf: - type: string pattern: ^[A-Z0-9]+$ description: Logitrail's inbound shipment identifier. - type: "null" type: anyOf: - type: string enum: - purchase_order - order_return description: Type of the inbound shipment. - type: "null" items: type: array items: type: object properties: item_id: description: Inbound Shipment Item ID type: string pattern: ^[a-f0-9]{24}$ product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product sku: type: string minLength: 1 description: SKU of the product gtin: description: GTIN (Barcode / EAN) of the product, if any type: string minLength: 1 name: type: string minLength: 1 description: Name of the product 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). required: - sku - name additionalProperties: false quantity: type: number minimum: 0 description: Expected quantity to arrive. Can be 0 if the merchant agreed to a line where nothing arrived (see `agreed_amount_stamp`). unit_purchase_price: anyOf: - type: number - type: "null" description: Declared purchase price per unit for this line item. Null when not set. currency: anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Null when not set. stocked_quantity: type: integer minimum: 0 maximum: 9007199254740991 description: Number of units of this product that have been received into the warehouse and assigned to an arrival batch. Includes units that subsequently moved on (picked, sent_out) or were flagged as incidents — those still arrived. Equals the sum of stocked_batches[].quantity. Zero when nothing has arrived yet for this line item. stocked_batches: type: array items: type: object properties: arrival_batch_id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Internal Logitrail identifier of the stocked arrival batch row. Stable across requests but not part of any other public API; treat as opaque. batch_number: anyOf: - type: string - type: "null" description: Batch number recorded at receiving for this stocked entry, if any. Null when the warehouse stored the units without a batch number. best_before_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Best-before / expiration date for this stocked entry, if recorded. quantity: type: integer minimum: 1 maximum: 9007199254740991 description: Number of units of this product stocked (and possibly moved on — picked / sent_out / incident — see DEV-708 semantics) tied to this arrival batch. first_seen_at: anyOf: - 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))$ - type: "null" description: Best-effort ISO 8601 timestamp of the earliest inbound_shipment.to_shelf movement linked to any article in this batch. Null when no such movement is linked to the batch (DEV-709 will replace this with a real ProductArrivalBatch.createdAt column). stocked_location: anyOf: - type: string - type: "null" description: Warehouse location into which the earliest inbound_shipment.to_shelf movement (the one whose timestamp is reported in first_seen_at) placed the goods. Informational; subsequent relocations are not reflected here. Null when first_seen_at is null. required: - arrival_batch_id - batch_number - best_before_date - quantity - first_seen_at - stocked_location additionalProperties: false description: Per-arrival-batch breakdown of the stocked quantity, grouped by ProductArrivalBatch and sorted by arrival_batch_id ascending. Empty when nothing has arrived yet. extra_services: description: LogitrailService attachments recorded against this line item. Public read returns active attachments only; archived ones are visible on internal-audience endpoints. Empty array when no attachments exist for the line. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false original_order: description: "For order-return inbound shipments: reference to the original order from which this returned line originated. Always belongs to the same merchant as the inbound shipment. Null when the line is not tied to an originating order." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id additionalProperties: false - type: "null" agreed_amount_stamp: description: Present when the merchant has agreed to the actually-stocked quantity for this under-delivered line (DEV-2102, via `_agree_amount`). Once set, `quantity` reflects the agreed amount and cannot be changed again through that action. Null when no agreement has been made. anyOf: - type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string from: type: number description: Originally expected quantity for this line before the merchant agreed to the stocked amount. to: type: number description: Quantity the merchant agreed to. Matches `quantity` on this line from this point on. required: - ts - from - to additionalProperties: false - type: "null" required: - product - quantity - unit_purchase_price - currency - stocked_quantity - stocked_batches additionalProperties: false description: List of product items to be expected to arrive in this inbound shipment. extra_items: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Inbound Shipment Extra Item ID item_details: type: object properties: title: type: string gtin: anyOf: - type: string - type: "null" title: GTIN if available description: GTIN (Barcode / EAN) of the extra item product, if it can be clearly identified. required: - title additionalProperties: false reason_code: type: string enum: - exp_date - broken - extra_items - unknown - not_ordered title: Reason Code (why extra item) description: Reason code set by Logitrail warehouse employee. Describes why this extra item is an extra item. quantity: anyOf: - type: number minimum: 1 - type: "null" description: Amount of extra items arrived. remarks: title: Free-form additional info for this extra-item row description: Free-form additional information recorded against the extra-item row by Logitrail warehouse staff. Surfaced to merchants alongside the row. Null when no remarks have been recorded. anyOf: - type: string - type: "null" merchants_decision: anyOf: - type: object properties: code: type: string enum: - already_corrected - stock_as_is - destroy - return_to_sender - other title: Handling instruction code for Logitrail description: Handling instruction code for Logitrail by the Merchant for the extra item. `stock_as_is` folds the item into the shipment automatically; `already_corrected` means the merchant already resolved the discrepancy themselves through another channel and no automation happens. merchant_remarks: title: Other remarks from the merchant to Logitrail description: Free-form instructions/remarks from the merchant to Logitrail. Optional for every code, including other. type: string product: title: Selected product for Stock as-is description: Reference to the merchant's catalog product this extra item was decided to be stocked as. Present only when code is stock_as_is. type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product required: - id additionalProperties: false decision_stamp: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false required: - code - decision_stamp additionalProperties: false - type: "null" required: - id - item_details - reason_code additionalProperties: false description: List of extra items that do not match any product or item in the inbound shipment. actual_arrival_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Actual arrival date of the inbound shipment. extra_services: description: LogitrailService attachments on this inbound shipment. Only active attachments are returned. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false warehouse: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: The shipment's fulfilling warehouse, resolved from the shipment's merchant's assigned warehouse. Null if the merchant does not resolve or has no warehouse assigned. Available regardless of arrival status. warehouse_location: anyOf: - type: object properties: id: type: string required: - id additionalProperties: false - type: "null" description: Raw arrival location (a WarehouseLocation id, a human-assigned string code, not an ObjectId). Null before the shipment has arrived. order_return: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id additionalProperties: false - type: "null" description: "The order return this shipment was created from, if any. Only set for type: order_return shipments, created when a merchant releases a to_shelf/resend_as_new decision for processing." required: - merchants_ref - sender_name - priority - merchant_remarks - estimated_arrival_date - id - status - merchant - created - type - items - extra_items - actual_arrival_date - warehouse - warehouse_location - order_return additionalProperties: false description: Inbound Shipment Data required: - inbound_shipment 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: Inbound shipment not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. "409": description: Inbound shipment is in processing and cannot be cancelled. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. /v1/inbound-shipments/{inboundShipmentId}/items/{itemId}: patch: summary: Update a single inbound shipment line item description: Partially updates a single line item by its `item_id`. Only the supplied fields are modified; omitted fields are left unchanged. Use this endpoint instead of the full-shipment PATCH when editing one item to avoid race conditions with concurrent updates to other items. Editing is allowed while the shipment is in `initial`, `confirmed`, `en_route`, or `problem`; any other status returns 409. Changing `quantity` is additionally refused with 409 when the line already has units arrived in the warehouse, or when its amount has already been agreed — the other fields remain editable in those cases. operationId: UpdateInboundShipmentItem security: - idp: - inbound_shipments: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: item: type: object properties: quantity: description: Expected quantity to arrive. Must be ≥ 1. type: number minimum: 1 unit_purchase_price: description: Declared purchase price per unit. Pass null to clear an existing value. anyOf: - type: number - type: "null" currency: description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Pass null to clear. anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" original_order: description: "For order-return inbound shipments: the originating sales order. Pass null to clear." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ required: - id - type: "null" additionalProperties: false description: Fields to update on the line item. required: - item responses: "200": description: The updated line item. content: application/json: schema: type: object properties: item: type: object properties: item_id: description: Inbound Shipment Item ID type: string pattern: ^[a-f0-9]{24}$ product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product sku: type: string minLength: 1 description: SKU of the product gtin: description: GTIN (Barcode / EAN) of the product, if any type: string minLength: 1 name: type: string minLength: 1 description: Name of the product 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). required: - sku - name additionalProperties: false quantity: type: number minimum: 0 description: Expected quantity to arrive. Can be 0 if the merchant agreed to a line where nothing arrived (see `agreed_amount_stamp`). unit_purchase_price: anyOf: - type: number - type: "null" description: Declared purchase price per unit for this line item. Null when not set. currency: anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Null when not set. stocked_quantity: type: integer minimum: 0 maximum: 9007199254740991 description: Number of units of this product that have been received into the warehouse and assigned to an arrival batch. Includes units that subsequently moved on (picked, sent_out) or were flagged as incidents — those still arrived. Equals the sum of stocked_batches[].quantity. Zero when nothing has arrived yet for this line item. stocked_batches: type: array items: type: object properties: arrival_batch_id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Internal Logitrail identifier of the stocked arrival batch row. Stable across requests but not part of any other public API; treat as opaque. batch_number: anyOf: - type: string - type: "null" description: Batch number recorded at receiving for this stocked entry, if any. Null when the warehouse stored the units without a batch number. best_before_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Best-before / expiration date for this stocked entry, if recorded. quantity: type: integer minimum: 1 maximum: 9007199254740991 description: Number of units of this product stocked (and possibly moved on — picked / sent_out / incident — see DEV-708 semantics) tied to this arrival batch. first_seen_at: anyOf: - 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))$ - type: "null" description: Best-effort ISO 8601 timestamp of the earliest inbound_shipment.to_shelf movement linked to any article in this batch. Null when no such movement is linked to the batch (DEV-709 will replace this with a real ProductArrivalBatch.createdAt column). stocked_location: anyOf: - type: string - type: "null" description: Warehouse location into which the earliest inbound_shipment.to_shelf movement (the one whose timestamp is reported in first_seen_at) placed the goods. Informational; subsequent relocations are not reflected here. Null when first_seen_at is null. required: - arrival_batch_id - batch_number - best_before_date - quantity - first_seen_at - stocked_location additionalProperties: false description: Per-arrival-batch breakdown of the stocked quantity, grouped by ProductArrivalBatch and sorted by arrival_batch_id ascending. Empty when nothing has arrived yet. extra_services: description: LogitrailService attachments recorded against this line item. Public read returns active attachments only; archived ones are visible on internal-audience endpoints. Empty array when no attachments exist for the line. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false original_order: description: "For order-return inbound shipments: reference to the original order from which this returned line originated. Always belongs to the same merchant as the inbound shipment. Null when the line is not tied to an originating order." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id additionalProperties: false - type: "null" agreed_amount_stamp: description: Present when the merchant has agreed to the actually-stocked quantity for this under-delivered line (DEV-2102, via `_agree_amount`). Once set, `quantity` reflects the agreed amount and cannot be changed again through that action. Null when no agreement has been made. anyOf: - type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string from: type: number description: Originally expected quantity for this line before the merchant agreed to the stocked amount. to: type: number description: Quantity the merchant agreed to. Matches `quantity` on this line from this point on. required: - ts - from - to additionalProperties: false - type: "null" required: - product - quantity - unit_purchase_price - currency - stocked_quantity - stocked_batches additionalProperties: false required: - item 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: Inbound shipment or item not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. "409": description: Inbound shipment is in a status that does not allow editing. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. delete: summary: Delete a line item from an inbound shipment description: Removes a single line item by its `item_id`. Deletion is allowed while the shipment is in `initial`, `confirmed`, `en_route`, or `problem`; any other status returns 409, as does an item that already has units arrived in the warehouse. operationId: DeleteInboundShipmentItem security: - idp: - inbound_shipments: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. responses: "204": description: Item removed. "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: Inbound shipment or item not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. "409": description: Shipment cannot be edited, or item has already had units arrived. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. /v1/inbound-shipments/{inboundShipmentId}/items: post: summary: Add a line item to an inbound shipment description: Appends a single new line item to the shipment. Editing is allowed while the shipment is in `initial`, `confirmed`, `en_route`, or `problem`; any other status returns 409. operationId: AddInboundShipmentItem security: - idp: - inbound_shipments: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: item: type: object properties: product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail technical ID of the product. Provide exactly one of id or sku. sku: type: string minLength: 1 description: Merchant's SKU of the product. Resolved server-side to an active product owned by the requesting merchant. Provide exactly one of id or sku. vendor_skus: description: Optional product-profile update. When set, the referenced product's vendor_skus array is replaced with this value as a side-effect of the inbound-shipment write. Omit to leave the profile untouched; pass an empty array to clear it. 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 quantity: type: number minimum: 1 description: Expected quantity to arrive unit_purchase_price: description: Declared purchase price per unit for this line item. Optional. Pass null to clear an existing value. anyOf: - type: number - type: "null" currency: description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR", "USD"). Optional. Pass null to clear. anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" original_order: description: "For order-return inbound shipments: reference to the original order from which the returned product originated. Must belong to the requesting merchant. Pass null to clear an existing reference; omit to leave it unchanged." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id - type: "null" required: - product - quantity description: The line item to add to the shipment. required: - item responses: "201": description: The newly created line item. content: application/json: schema: type: object properties: item: type: object properties: item_id: description: Inbound Shipment Item ID type: string pattern: ^[a-f0-9]{24}$ product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product sku: type: string minLength: 1 description: SKU of the product gtin: description: GTIN (Barcode / EAN) of the product, if any type: string minLength: 1 name: type: string minLength: 1 description: Name of the product 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). required: - sku - name additionalProperties: false quantity: type: number minimum: 0 description: Expected quantity to arrive. Can be 0 if the merchant agreed to a line where nothing arrived (see `agreed_amount_stamp`). unit_purchase_price: anyOf: - type: number - type: "null" description: Declared purchase price per unit for this line item. Null when not set. currency: anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Null when not set. stocked_quantity: type: integer minimum: 0 maximum: 9007199254740991 description: Number of units of this product that have been received into the warehouse and assigned to an arrival batch. Includes units that subsequently moved on (picked, sent_out) or were flagged as incidents — those still arrived. Equals the sum of stocked_batches[].quantity. Zero when nothing has arrived yet for this line item. stocked_batches: type: array items: type: object properties: arrival_batch_id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Internal Logitrail identifier of the stocked arrival batch row. Stable across requests but not part of any other public API; treat as opaque. batch_number: anyOf: - type: string - type: "null" description: Batch number recorded at receiving for this stocked entry, if any. Null when the warehouse stored the units without a batch number. best_before_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Best-before / expiration date for this stocked entry, if recorded. quantity: type: integer minimum: 1 maximum: 9007199254740991 description: Number of units of this product stocked (and possibly moved on — picked / sent_out / incident — see DEV-708 semantics) tied to this arrival batch. first_seen_at: anyOf: - 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))$ - type: "null" description: Best-effort ISO 8601 timestamp of the earliest inbound_shipment.to_shelf movement linked to any article in this batch. Null when no such movement is linked to the batch (DEV-709 will replace this with a real ProductArrivalBatch.createdAt column). stocked_location: anyOf: - type: string - type: "null" description: Warehouse location into which the earliest inbound_shipment.to_shelf movement (the one whose timestamp is reported in first_seen_at) placed the goods. Informational; subsequent relocations are not reflected here. Null when first_seen_at is null. required: - arrival_batch_id - batch_number - best_before_date - quantity - first_seen_at - stocked_location additionalProperties: false description: Per-arrival-batch breakdown of the stocked quantity, grouped by ProductArrivalBatch and sorted by arrival_batch_id ascending. Empty when nothing has arrived yet. extra_services: description: LogitrailService attachments recorded against this line item. Public read returns active attachments only; archived ones are visible on internal-audience endpoints. Empty array when no attachments exist for the line. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false original_order: description: "For order-return inbound shipments: reference to the original order from which this returned line originated. Always belongs to the same merchant as the inbound shipment. Null when the line is not tied to an originating order." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id additionalProperties: false - type: "null" agreed_amount_stamp: description: Present when the merchant has agreed to the actually-stocked quantity for this under-delivered line (DEV-2102, via `_agree_amount`). Once set, `quantity` reflects the agreed amount and cannot be changed again through that action. Null when no agreement has been made. anyOf: - type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string from: type: number description: Originally expected quantity for this line before the merchant agreed to the stocked amount. to: type: number description: Quantity the merchant agreed to. Matches `quantity` on this line from this point on. required: - ts - from - to additionalProperties: false - type: "null" required: - product - quantity - unit_purchase_price - currency - stocked_quantity - stocked_batches additionalProperties: false required: - item 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: Inbound shipment not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. "409": description: Inbound shipment is in a status that does not allow editing. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. /v1/inbound-shipments/{inboundShipmentId}/extra_services: post: summary: Attach a LogitrailService to an inbound shipment as a whole description: Attaches a service that operates at shipment scope (e.g. arrival inspection, full-pallet handling, or any service with applicable_scopes covering inbound_shipment) to an inbound shipment. The service is identified by `id` or `code`; the server resolves the catalog row, verifies the service is enabled, applicable to inbound-shipment scope, and available to the requesting merchant. operationId: AttachServiceToInboundShipment security: - idp: - inbound_shipments: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: service_attachment: type: object properties: service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. description: Service to attach. Provide either `id` or `code`; the server resolves the other. quantity: description: Optional per-attachment quantity. type: integer minimum: 1 maximum: 9007199254740991 parameters: description: Service-specific extras. Validated against the per-service Zod schema (when registered) at attach time. type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. type: string required: - service description: Service attachment to add to the inbound shipment as a whole. Provide the service reference by `id` or `code`; the server resolves the other. required: - service_attachment responses: "201": description: Newly created service attachment. content: application/json: schema: type: object properties: service_attachment: 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false description: Newly created service attachment. required: - service_attachment 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 "403": description: Merchant is not allowed to attach this service (per onlyForMerchants / notForMerchants). content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false description: Error response body. `error_code` carries the structured eligibility rejection code (e.g. `service_disabled`, `scope_not_applicable`, `merchant_not_allowed`). "404": description: Inbound shipment or service not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false description: Error response body. `error_code` carries the structured eligibility rejection code (e.g. `service_disabled`, `scope_not_applicable`, `merchant_not_allowed`). "409": description: Service is disabled in the catalog and cannot be attached. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false description: Error response body. `error_code` carries the structured eligibility rejection code (e.g. `service_disabled`, `scope_not_applicable`, `merchant_not_allowed`). /v1/inbound-shipments/{inboundShipmentId}/items/{itemId}/extra_services: post: summary: Attach a LogitrailService to an inbound shipment line item description: Attaches one or more services (assembly, labelling, inspection, special packaging, etc.) to a specific line item on an inbound shipment. The service is identified by `id` or `code`; the server resolves the catalog row, verifies the service is enabled, applicable to inbound-shipment-item scope, and available to the requesting merchant. The attachment is recorded with quantity, optional service-specific parameters, optional merchant remarks, and a server-generated created stamp. operationId: AttachServiceToInboundShipmentItem security: - idp: - inbound_shipments: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: service_attachment: type: object properties: service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. description: Service to attach. Provide either `id` or `code`; the server resolves the other. quantity: description: Optional per-attachment quantity. type: integer minimum: 1 maximum: 9007199254740991 parameters: description: Service-specific extras. Validated against the per-service Zod schema (when registered) at attach time. type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. type: string required: - service description: Service attachment to add to the inbound shipment line item. Provide the service reference by `id` or `code`; the server resolves the other. required: - service_attachment responses: "201": description: Newly created service attachment. content: application/json: schema: type: object properties: service_attachment: 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false description: Newly created service attachment. required: - service_attachment 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 "403": description: Merchant is not allowed to attach this service (per onlyForMerchants / notForMerchants). content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false description: Error response body. `error_code` carries the structured eligibility rejection code (e.g. `service_disabled`, `scope_not_applicable`, `merchant_not_allowed`). "404": description: Inbound shipment, line item, or service not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false description: Error response body. `error_code` carries the structured eligibility rejection code (e.g. `service_disabled`, `scope_not_applicable`, `merchant_not_allowed`). "409": description: Service is disabled in the catalog and cannot be attached. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: {} required: - message additionalProperties: false description: Error response body. `error_code` carries the structured eligibility rejection code (e.g. `service_disabled`, `scope_not_applicable`, `merchant_not_allowed`). /v1/inbound-shipments/{inboundShipmentId}/extra_items/{extraItemId}: post: summary: Update Extra Item (merchants_decision only) description: Applies the merchant's handling decision to an extra-item subdocument. Accepts only the `merchants_decision` envelope; the merchant may set `code` and/or `merchant_remarks` together or separately, but no other extra-item fields. `product` (a reference to a catalog product) is required when `code` is `stock_as_is`. A decision, once submitted, cannot be changed by the merchant — submitting `code` again after a decision already exists is rejected. operationId: UpdateInboundShipmentExtraItem security: - idp: - inbound_shipments: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: extra_item: type: object properties: merchants_decision: type: object properties: code: description: "Handling instruction code for Logitrail. Omit to leave the existing code unchanged. Allowed values: destroy, return_to_sender, already_corrected, stock_as_is, other. `stock_as_is` folds the item into the shipment automatically; `already_corrected` means the merchant already resolved the discrepancy themselves through another channel and no automation happens." type: string merchant_remarks: description: Free-form remarks from the merchant to Logitrail. Omit to leave existing remarks unchanged. Optional for every code, including other. type: string product: description: Reference to the merchant's catalog product this extra item is being stocked as. Required when code is stock_as_is. type: object properties: id: type: string required: - id auto_add_to_items: description: When code is stock_as_is, whether Logitrail should automatically add this extra item's product and amount to the shipment's normal item list. Defaults to true. type: boolean description: Partial update of the merchant decision envelope. Provide `code` and/or `merchant_remarks` (at least one required). required: - merchants_decision description: Merchant-allowed extra-item updates. Only the merchants_decision envelope is settable; other fields require the internal endpoint. required: - extra_item description: Merchant-facing Update Extra Item body. The strict runtime schema is enforced by `editExtraItemRequestEventSchema`. responses: "200": description: Updated extra item. content: application/json: schema: type: object properties: extra_item: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Inbound Shipment Extra Item ID item_details: type: object properties: title: type: string gtin: anyOf: - type: string - type: "null" title: GTIN if available description: GTIN (Barcode / EAN) of the extra item product, if it can be clearly identified. required: - title additionalProperties: false reason_code: type: string enum: - exp_date - broken - extra_items - unknown - not_ordered title: Reason Code (why extra item) description: Reason code set by Logitrail warehouse employee. Describes why this extra item is an extra item. quantity: anyOf: - type: number minimum: 1 - type: "null" description: Amount of extra items arrived. remarks: title: Free-form additional info for this extra-item row description: Free-form additional information recorded against the extra-item row by Logitrail warehouse staff. Surfaced to merchants alongside the row. Null when no remarks have been recorded. anyOf: - type: string - type: "null" merchants_decision: anyOf: - type: object properties: code: type: string enum: - already_corrected - stock_as_is - destroy - return_to_sender - other title: Handling instruction code for Logitrail description: Handling instruction code for Logitrail by the Merchant for the extra item. `stock_as_is` folds the item into the shipment automatically; `already_corrected` means the merchant already resolved the discrepancy themselves through another channel and no automation happens. merchant_remarks: title: Other remarks from the merchant to Logitrail description: Free-form instructions/remarks from the merchant to Logitrail. Optional for every code, including other. type: string product: title: Selected product for Stock as-is description: Reference to the merchant's catalog product this extra item was decided to be stocked as. Present only when code is stock_as_is. type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product required: - id additionalProperties: false decision_stamp: type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string required: - ts additionalProperties: false required: - code - decision_stamp additionalProperties: false - type: "null" required: - id - item_details - reason_code additionalProperties: false cs_notified: description: Present only when this update set `merchants_decision.code`. `true` means a CS case notification was successfully handed off (DEV-2033) — this confirms the request was accepted, not that the case has finished being created, since raising happens asynchronously. `false` means the handoff itself failed; the decision above was still saved. Absent for remarks-only updates that did not touch `code`. type: boolean item_merged: description: Present only when this update set `merchants_decision.code` to stock_as_is and `auto_add_to_items` was not false. `true` means the extra item's product and amount were folded into the shipment's normal item list. Absent for every other code or for remarks-only updates. type: boolean auto_transitioned_to_processed: description: Present only when this update set `merchants_decision.code`. `true` means this decision was the last thing blocking the shipment and it was automatically transitioned from processing to processed. Absent for remarks-only updates that did not touch `code`. type: boolean required: - extra_item 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: Inbound shipment or extra item not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. "409": description: A decision has already been submitted for this extra item; `code` cannot be changed once set. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. /v1/inbound-shipments/{inboundShipmentId}/items/{itemId}/_agree_amount: post: summary: Agree to the stocked amount for an under-delivered line description: For a line item where less arrived than expected, accepts the actually-stocked quantity in place of the originally-expected one. The new quantity is always derived server-side from what was received into the warehouse — the request body carries no fields. Only allowed while the shipment is in status initial, confirmed, en_route, or problem — not during arrived_at_warehouse or processing, when warehouse staff may be actively counting/shelving. Once agreed, this cannot be changed again through this endpoint. If this was the last outstanding extra item or under-delivered line, the shipment automatically transitions from processing to processed. operationId: AgreeInboundShipmentItemAmount security: - idp: - inbound_shipments: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. responses: "200": description: Updated line item. content: application/json: schema: type: object properties: item: type: object properties: item_id: description: Inbound Shipment Item ID type: string pattern: ^[a-f0-9]{24}$ product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the product sku: type: string minLength: 1 description: SKU of the product gtin: description: GTIN (Barcode / EAN) of the product, if any type: string minLength: 1 name: type: string minLength: 1 description: Name of the product 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). required: - sku - name additionalProperties: false quantity: type: number minimum: 0 description: Expected quantity to arrive. Can be 0 if the merchant agreed to a line where nothing arrived (see `agreed_amount_stamp`). unit_purchase_price: anyOf: - type: number - type: "null" description: Declared purchase price per unit for this line item. Null when not set. currency: anyOf: - type: string minLength: 3 maxLength: 3 - type: "null" description: ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Null when not set. stocked_quantity: type: integer minimum: 0 maximum: 9007199254740991 description: Number of units of this product that have been received into the warehouse and assigned to an arrival batch. Includes units that subsequently moved on (picked, sent_out) or were flagged as incidents — those still arrived. Equals the sum of stocked_batches[].quantity. Zero when nothing has arrived yet for this line item. stocked_batches: type: array items: type: object properties: arrival_batch_id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Internal Logitrail identifier of the stocked arrival batch row. Stable across requests but not part of any other public API; treat as opaque. batch_number: anyOf: - type: string - type: "null" description: Batch number recorded at receiving for this stocked entry, if any. Null when the warehouse stored the units without a batch number. best_before_date: anyOf: - type: string format: date 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])))$ - type: "null" description: Best-before / expiration date for this stocked entry, if recorded. quantity: type: integer minimum: 1 maximum: 9007199254740991 description: Number of units of this product stocked (and possibly moved on — picked / sent_out / incident — see DEV-708 semantics) tied to this arrival batch. first_seen_at: anyOf: - 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))$ - type: "null" description: Best-effort ISO 8601 timestamp of the earliest inbound_shipment.to_shelf movement linked to any article in this batch. Null when no such movement is linked to the batch (DEV-709 will replace this with a real ProductArrivalBatch.createdAt column). stocked_location: anyOf: - type: string - type: "null" description: Warehouse location into which the earliest inbound_shipment.to_shelf movement (the one whose timestamp is reported in first_seen_at) placed the goods. Informational; subsequent relocations are not reflected here. Null when first_seen_at is null. required: - arrival_batch_id - batch_number - best_before_date - quantity - first_seen_at - stocked_location additionalProperties: false description: Per-arrival-batch breakdown of the stocked quantity, grouped by ProductArrivalBatch and sorted by arrival_batch_id ascending. Empty when nothing has arrived yet. extra_services: description: LogitrailService attachments recorded against this line item. Public read returns active attachments only; archived ones are visible on internal-audience endpoints. Empty array when no attachments exist for the line. 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: Per-attachment unique id. service: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's internal technical ID of the LogitrailService. code: anyOf: - type: string minLength: 1 description: Canonical, unique code for the service (e.g. POSTIPAKETTI). Carried on the catalog row; surfaced on read DTOs and accepted as a write-side alternative to `id`. - type: "null" description: Canonical service code joined from the catalog at read time. Null when the catalog row pre-dates the mono `code` field. required: - id - code additionalProperties: false description: Reference to the LogitrailService catalog row this attachment points at. quantity: description: Optional per-attachment quantity. Null/absent for flat-priced services. anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" parameters: description: Service-specific extras. Open at storage; per-service Zod schemas may tighten this on attach (DEV-780). type: object propertyNames: type: string additionalProperties: {} merchant_remarks: description: Public free-form remarks from the merchant. Surfaced on every endpoint. anyOf: - type: string - type: "null" created_stamp: type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false description: Stamp recording who attached the service and when. Server-generated on attach. archived_stamp: description: Stamp recording who archived the attachment and when. Present only when `status === "archived"`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false status: type: string enum: - active - archived description: Lifecycle status of this attachment. completion_stamp: description: Stamp recording when (and by whom) the attached service was marked completed. Set by DEV-911 (`POST .../_completed`) and cleared by DEV-912 (`DELETE`). Absent when the service has not been marked completed. Optional completion comments are carried under `completion_stamp.p.comment`. type: object properties: ts: description: Stamp timestamp. ISO 8601 string accepted on input; surfaced as Date. type: string user: type: string source: type: string p: type: object propertyNames: type: string additionalProperties: {} required: - ts additionalProperties: false required: - id - service - created_stamp - status additionalProperties: false original_order: description: "For order-return inbound shipments: reference to the original order from which this returned line originated. Always belongs to the same merchant as the inbound shipment. Null when the line is not tied to an originating order." anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Logitrail's technical ID of the order. required: - id additionalProperties: false - type: "null" agreed_amount_stamp: description: Present when the merchant has agreed to the actually-stocked quantity for this under-delivered line (DEV-2102, via `_agree_amount`). Once set, `quantity` reflects the agreed amount and cannot be changed again through that action. Null when no agreement has been made. anyOf: - type: object properties: ts: 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))$ title: Timestamp description: Timestamp in ISO 8601 format user: title: User description: User and/or client information. type: string from: type: number description: Originally expected quantity for this line before the merchant agreed to the stocked amount. to: type: number description: Quantity the merchant agreed to. Matches `quantity` on this line from this point on. required: - ts - from - to additionalProperties: false - type: "null" required: - product - quantity - unit_purchase_price - currency - stocked_quantity - stocked_batches additionalProperties: false auto_transitioned_to_processed: type: boolean description: True when agreeing this amount was the last thing blocking the shipment — every extra item already had a decision and every other under-delivered line was already agreed — so the shipment was automatically transitioned from processing to processed. required: - item - auto_transitioned_to_processed 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: Inbound shipment or line item not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. "409": description: The shipment status doesn't allow this action (error_code AGREE_AMOUNT_STATUS_NOT_ALLOWED), the line has no shortfall to agree to (AGREE_AMOUNT_NO_SHORTFALL), or an amount has already been agreed for this line item and cannot be changed (AGREE_AMOUNT_ALREADY_SUBMITTED). content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. /v1/inbound-shipments/{inboundShipmentId}/attachments: get: summary: Get Inbound Shipment Attachments description: Returns the attachment list for a single inbound shipment with temporary download URLs valid for 30 minutes. operationId: GetInboundShipmentAttachments security: - idp: - inbound_shipments:read parameters: [] responses: "200": description: Attachments of the inbound shipment. 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 example: 5f9b1b9b9b9b9b9b9b9b9b9b 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. file_name: type: string description: Filename of the attachment. Usually technical filename from the scanning device. mime: type: string description: MIME type of the attachment. is_archived: type: boolean description: Is the attachment archived? Archived attachments cannot be retrieved anymore. Attachments will be archived after 1 year. download_link: description: Download link of the attachment, if available. type: object properties: url: type: string description: Download URL of the attachment. Use this URL to receive a copy of the attachment file or display it in a browser. 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 whichafter the URL does not work anymore. Links are usually valid 30 minutes, but expect also other values. required: - url - valid_until additionalProperties: false required: - id - uploaded_at - file_name - mime - is_archived additionalProperties: false description: List of attachments of the inbound shipment. 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: Inbound shipment not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Inbound-shipment error response body. components: securitySchemes: idp: type: oauth2 flows: clientCredentials: tokenUrl: https://idp.logitrail.com/realms/logitrail/protocol/openid-connect/token scopes: inbound_shipments:read: Read inbound shipment data inbound_shipments:manage: Manage inbound shipment data