openapi: 3.1.0 info: title: Order Management Service version: 2026-08-08.2742812626 description: API for Order Management. servers: - url: https://api-1.test.logitrail.com description: Test / Development Server - url: https://api-1.logitrail.com description: Production Server paths: /v1/orders: post: summary: Create order description: Creates a new order for a merchant. operationId: CreateOrder security: - idp: - orders: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: order: type: object properties: customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts expires: 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" required: - id - comment - created - expires - type: "null" process_hold: anyOf: - type: boolean - type: "null" items: type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ sku: type: string minLength: 1 name: type: string fulfillment_by: type: string enum: - logitrail - merchant components: anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string sku: anyOf: - type: string - type: "null" required: - id amount: type: integer minimum: 1 maximum: 9007199254740991 required: - product - amount - type: "null" fulfillment_by: anyOf: - type: string enum: - logitrail - merchant - type: "null" title: Fulfillment route (optional override) description: Optional override for this order line's fulfillment route. When omitted, the line inherits the product profile's `fulfillment_by` value; if the product profile also has no value (legacy products), the line falls back to `logitrail`. When supplied, this value overrides the product default for this line. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Trimmed of surrounding whitespace; up to 2000 characters after trimming. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 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 required: - product - quantity no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. extra_services: description: LogitrailService attachments on this order. 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 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 merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system. Stored on the order and returned on read. requested_delivery_method: description: Raw delivery-method hint. null clears requestedDeliveryMethodCode/Info. anyOf: - type: object properties: code: type: string minLength: 1 info: anyOf: - type: string - type: "null" required: - code additionalProperties: false - type: "null" requested_delivery_service: description: Select the requested LogitrailService by id (preferred) or code. null clears the field. anyOf: - type: object properties: id: description: LogitrailService ObjectId. Takes precedence over code when both are present. Resolved against the logitrail-service-catalog at write time. type: string pattern: ^[0-9a-f]{24}$ code: description: LogitrailService canonical code (e.g. `POSTIPAKETTI`). Used as fallback when id is absent. Resolved against the logitrail-service-catalog at write time. type: string minLength: 1 additionalProperties: false - type: "null" delivery_service: description: Select the actual LogitrailService by id (preferred) or code. null clears the field. anyOf: - type: object properties: id: description: LogitrailService ObjectId. Takes precedence over code when both are present. type: string pattern: ^[0-9a-f]{24}$ code: description: LogitrailService canonical code. Used as fallback when id is absent. type: string minLength: 1 additionalProperties: false - type: "null" requested_pickup_point: description: Raw pickup-point hint. null clears requestedPickupPointCode/Info. anyOf: - type: object properties: code: type: string minLength: 1 info: anyOf: - type: string - type: "null" required: - code additionalProperties: false - type: "null" pickup_point: description: Select the resolved PickupPoint by id. null clears the field. anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: PickupPoint Mongo ObjectId (24 hex chars). Resolved against the pickup-point-service collection at write time. required: - id additionalProperties: false - type: "null" requested_delivery_destination: description: "@deprecated Use pickup_point instead. Equivalent to pickup_point: { id }; pickup_point wins if both are present." anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: PickupPoint Mongo ObjectId (24 hex chars). Resolved against the pickup-point-service collection at write time. required: - id additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" status: description: Initial status for the new order. `draft` (default when omitted) leaves the order in draft. `confirmed` runs the draft→confirmed transition gates at the end of the create call; must include at least one line item. type: string enum: - draft - confirmed required: - order responses: "201": description: Order created content: application/json: schema: type: object properties: order: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" additionalProperties: false our_id: anyOf: - type: string - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" status: type: string enum: - draft - passive - confirmed - waiting_products - problem - processing - processed - returning - returned - cancelled - deleted anonymized: description: Present (with `ts`) once the order has been anonymized — indicates customer fields have been wiped. Null/absent otherwise. 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))$ description: Timestamp when anonymization was applied. required: - ts additionalProperties: false description: Present when the order has been anonymized. Absent otherwise. - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" process_hold: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" items: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Order line stable identifier (24-hex Mongo ObjectId). Used as the path parameter on the per-item PATCH endpoint. product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string minLength: 1 sku: type: string minLength: 1 components: description: Component/sub-product breakdown when this order line's product is a bundle. Omitted for non-bundle lines. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: description: Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: "null" required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: Amount of this sub-product included per unit of the order line's product. required: - product - amount additionalProperties: false - type: "null" required: - id - name - sku additionalProperties: false fulfillment_by: type: string enum: - logitrail - merchant title: Fulfillment route description: Fulfillment route for this order line. `logitrail` means Logitrail's warehouse picks and ships the line; `merchant` means the merchant fulfills it themselves and Logitrail does not pick or ship it. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency additionalProperties: false - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Up to 2000 characters. Omitted when no note has been recorded. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 required: - id - product - fulfillment_by - quantity additionalProperties: false created_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 (ISO 8601) when the order was created in Logitrail. merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system, if provided by the merchant. no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. requested_delivery_method: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" mapping_status: anyOf: - type: string - type: "null" required: - code - info - mapping_status additionalProperties: false - type: "null" description: Raw delivery-method hint from the inbound channel (code + free-text info + mapping status). Null when not set. requested_delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The LogitrailService selected as the requested delivery method. Null when not set or not yet resolved. delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The actual LogitrailService used for fulfilment. Null when not set. requested_pickup_point: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" required: - code - info additionalProperties: false - type: "null" description: Raw pickup-point hint (code + free-text info). Null when not set. pickup_point: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false - type: "null" description: The resolved PickupPoint entity. Null when not set or not yet resolved. requested_delivery_destination: anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" description: "@deprecated Use pickup_point instead. Kept for backwards compatibility — mirrors pickup_point on read." extra_services: description: LogitrailService attachments on this order. 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 required: - id - customer - our_id - status - items - created_at additionalProperties: false required: - order 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 get: summary: List orders description: Returns a paginated list of merchant orders. Multiple filters may be combined; they are AND-merged in the resulting query. operationId: ListOrders security: - idp: - orders: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: status schema: description: Exact match on order status. See OrderStatusEnum for the list of values. type: string enum: - draft - passive - confirmed - waiting_products - problem - processing - processed - returning - returned - cancelled - deleted description: Exact match on order status. See OrderStatusEnum for the list of values. - in: query name: has_product_id schema: description: Filter orders that contain a line referencing this product (Mongo ObjectId, 24 hex chars). type: string pattern: ^[0-9a-f]{24}$ description: Filter orders that contain a line referencing this product (Mongo ObjectId, 24 hex chars). - in: query name: our_id schema: description: Exact match on the Logitrail-issued order ID (e.g. "T1234ABCD"). Same value that appears as `our_id` in the order DTO. Globally unique across all merchants — at most 1 result will be returned (and only if the order belongs to the calling merchant). type: string pattern: ^T\d{4,}[A-Z0-9]{4}$ description: Exact match on the Logitrail-issued order ID (e.g. "T1234ABCD"). Same value that appears as `our_id` in the order DTO. Globally unique across all merchants — at most 1 result will be returned (and only if the order belongs to the calling merchant). - in: query name: merchants_id schema: description: Exact match on the merchant’s own order number. Same value that appears as `merchants_id` in the order DTO. Not guaranteed unique within a merchant in legacy data — may return multiple results. type: string minLength: 1 description: Exact match on the merchant’s own order number. Same value that appears as `merchants_id` in the order DTO. Not guaranteed unique within a merchant in legacy data — may return multiple results. - in: query name: customer_name_search schema: description: Case-insensitive substring match across customer first name, last name, and organisation (minimum 3 characters). Returns orders where any of those fields contains the search term. type: string minLength: 3 description: Case-insensitive substring match across customer first name, last name, and organisation (minimum 3 characters). Returns orders where any of those fields contains the search term. - in: query name: q schema: description: "Unified search (minimum 3 characters). Auto-detects the input shape: a string matching the Logitrail order ID format (T + 4+ digits + 4 alphanum) is treated as an exact `our_id` lookup; any other input is matched against `merchants_id` (exact), customer first/last name and organisation (substring, case-insensitive), and the carrier tracking code of any shipment linked to the order (exact match, covers multi-parcel shipments)." type: string minLength: 3 description: "Unified search (minimum 3 characters). Auto-detects the input shape: a string matching the Logitrail order ID format (T + 4+ digits + 4 alphanum) is treated as an exact `our_id` lookup; any other input is matched against `merchants_id` (exact), customer first/last name and organisation (substring, case-insensitive), and the carrier tracking code of any shipment linked to the order (exact match, covers multi-parcel shipments)." - in: query name: quick_filter schema: description: "Server-defined named filter bundle. Expands into a set of underlying criteria before executing the query. Combinable with explicit filters (AND-merge). Currently supported: `open` — excludes terminal and pre-flight statuses; expands to status ∈ [confirmed, waiting_products, problem, processing, returning]." type: string enum: - open description: "Server-defined named filter bundle. Expands into a set of underlying criteria before executing the query. Combinable with explicit filters (AND-merge). Currently supported: `open` — excludes terminal and pre-flight statuses; expands to status ∈ [confirmed, waiting_products, problem, processing, returning]." - in: query name: created_at_min schema: description: Inclusive lower bound on the order 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 order 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 order 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 order creation timestamp. Accepts YYYY-MM-DD (interpreted as end-of-day UTC) or a full ISO 8601 datetime. - in: query name: has_product_min_counts schema: description: "JSON array of per-product quantity thresholds: [{\"product_id\":\"<24-hex ObjectId>\",\"min_count\":60}, ...]. An order matches an entry when the sum of that product's quantity across all its lines is at least min_count. How multiple entries combine is controlled by has_product_min_counts_match." type: string description: "JSON array of per-product quantity thresholds: [{\"product_id\":\"<24-hex ObjectId>\",\"min_count\":60}, ...]. An order matches an entry when the sum of that product's quantity across all its lines is at least min_count. How multiple entries combine is controlled by has_product_min_counts_match." - in: query name: has_product_min_counts_match schema: default: all description: 'How multiple has_product_min_counts entries combine. "all" (default): the order must satisfy every entry. "any": at least one entry. Has no effect with a single entry.' type: string enum: - any - all description: 'How multiple has_product_min_counts entries combine. "all" (default): the order must satisfy every entry. "any": at least one entry. Has no effect with a single entry.' - in: query name: offset schema: default: 0 description: Pagination offset. Defaults to 0. type: number minimum: 0 description: Pagination offset. Defaults to 0. - in: query name: limit schema: default: 250 description: Maximum number of orders to return. Defaults to 250, capped at 1000. type: number minimum: 1 maximum: 1000 description: Maximum number of orders to return. Defaults to 250, capped at 1000. responses: "200": description: List of orders content: application/json: schema: type: object properties: orders: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" additionalProperties: false our_id: anyOf: - type: string - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" status: type: string enum: - draft - passive - confirmed - waiting_products - problem - processing - processed - returning - returned - cancelled - deleted anonymized: description: Present (with `ts`) once the order has been anonymized — indicates customer fields have been wiped. Null/absent otherwise. 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))$ description: Timestamp when anonymization was applied. required: - ts additionalProperties: false description: Present when the order has been anonymized. Absent otherwise. - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" process_hold: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" items: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Order line stable identifier (24-hex Mongo ObjectId). Used as the path parameter on the per-item PATCH endpoint. product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string minLength: 1 sku: type: string minLength: 1 components: description: Component/sub-product breakdown when this order line's product is a bundle. Omitted for non-bundle lines. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: description: Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: "null" required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: Amount of this sub-product included per unit of the order line's product. required: - product - amount additionalProperties: false - type: "null" required: - id - name - sku additionalProperties: false fulfillment_by: type: string enum: - logitrail - merchant title: Fulfillment route description: Fulfillment route for this order line. `logitrail` means Logitrail's warehouse picks and ships the line; `merchant` means the merchant fulfills it themselves and Logitrail does not pick or ship it. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency additionalProperties: false - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Up to 2000 characters. Omitted when no note has been recorded. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 required: - id - product - fulfillment_by - quantity additionalProperties: false created_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 (ISO 8601) when the order was created in Logitrail. merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system, if provided by the merchant. no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. requested_delivery_method: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" mapping_status: anyOf: - type: string - type: "null" required: - code - info - mapping_status additionalProperties: false - type: "null" description: Raw delivery-method hint from the inbound channel (code + free-text info + mapping status). Null when not set. requested_delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The LogitrailService selected as the requested delivery method. Null when not set or not yet resolved. delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The actual LogitrailService used for fulfilment. Null when not set. requested_pickup_point: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" required: - code - info additionalProperties: false - type: "null" description: Raw pickup-point hint (code + free-text info). Null when not set. pickup_point: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false - type: "null" description: The resolved PickupPoint entity. Null when not set or not yet resolved. requested_delivery_destination: anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" description: "@deprecated Use pickup_point instead. Kept for backwards compatibility — mirrors pickup_point on read." extra_services: description: LogitrailService attachments on this order. 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 required: - id - customer - our_id - status - items - created_at additionalProperties: false required: - orders 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/orders/{orderId}: get: summary: Get order description: Returns a merchant order by ID. operationId: GetOrder security: - idp: - orders: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: Order details content: application/json: schema: type: object properties: order: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" additionalProperties: false our_id: anyOf: - type: string - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" status: type: string enum: - draft - passive - confirmed - waiting_products - problem - processing - processed - returning - returned - cancelled - deleted anonymized: description: Present (with `ts`) once the order has been anonymized — indicates customer fields have been wiped. Null/absent otherwise. 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))$ description: Timestamp when anonymization was applied. required: - ts additionalProperties: false description: Present when the order has been anonymized. Absent otherwise. - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" process_hold: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" items: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Order line stable identifier (24-hex Mongo ObjectId). Used as the path parameter on the per-item PATCH endpoint. product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string minLength: 1 sku: type: string minLength: 1 components: description: Component/sub-product breakdown when this order line's product is a bundle. Omitted for non-bundle lines. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: description: Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: "null" required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: Amount of this sub-product included per unit of the order line's product. required: - product - amount additionalProperties: false - type: "null" required: - id - name - sku additionalProperties: false fulfillment_by: type: string enum: - logitrail - merchant title: Fulfillment route description: Fulfillment route for this order line. `logitrail` means Logitrail's warehouse picks and ships the line; `merchant` means the merchant fulfills it themselves and Logitrail does not pick or ship it. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency additionalProperties: false - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Up to 2000 characters. Omitted when no note has been recorded. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 required: - id - product - fulfillment_by - quantity additionalProperties: false created_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 (ISO 8601) when the order was created in Logitrail. merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system, if provided by the merchant. no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. requested_delivery_method: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" mapping_status: anyOf: - type: string - type: "null" required: - code - info - mapping_status additionalProperties: false - type: "null" description: Raw delivery-method hint from the inbound channel (code + free-text info + mapping status). Null when not set. requested_delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The LogitrailService selected as the requested delivery method. Null when not set or not yet resolved. delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The actual LogitrailService used for fulfilment. Null when not set. requested_pickup_point: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" required: - code - info additionalProperties: false - type: "null" description: Raw pickup-point hint (code + free-text info). Null when not set. pickup_point: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false - type: "null" description: The resolved PickupPoint entity. Null when not set or not yet resolved. requested_delivery_destination: anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" description: "@deprecated Use pickup_point instead. Kept for backwards compatibility — mirrors pickup_point on read." extra_services: description: LogitrailService attachments on this order. 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 required: - id - customer - our_id - status - items - created_at additionalProperties: false required: - order 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: Update order description: Updates an existing merchant order. operationId: UpdateOrder security: - idp: - orders: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: order: type: object properties: customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts expires: 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" required: - id - comment - created - expires - type: "null" items: type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ sku: type: string minLength: 1 name: type: string fulfillment_by: type: string enum: - logitrail - merchant components: anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string sku: anyOf: - type: string - type: "null" required: - id amount: type: integer minimum: 1 maximum: 9007199254740991 required: - product - amount - type: "null" fulfillment_by: anyOf: - type: string enum: - logitrail - merchant - type: "null" title: Fulfillment route (optional override) description: Optional override for this order line's fulfillment route. When omitted, the line inherits the product profile's `fulfillment_by` value; if the product profile also has no value (legacy products), the line falls back to `logitrail`. When supplied, this value overrides the product default for this line. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Trimmed of surrounding whitespace; up to 2000 characters after trimming. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 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 required: - product - quantity no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. extra_services: description: LogitrailService attachments on this order. 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 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 merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system. Stored on the order and returned on read. requested_delivery_method: description: Raw delivery-method hint. null clears requestedDeliveryMethodCode/Info. anyOf: - type: object properties: code: type: string minLength: 1 info: anyOf: - type: string - type: "null" required: - code additionalProperties: false - type: "null" requested_delivery_service: description: Select the requested LogitrailService by id (preferred) or code. null clears the field. anyOf: - type: object properties: id: description: LogitrailService ObjectId. Takes precedence over code when both are present. Resolved against the logitrail-service-catalog at write time. type: string pattern: ^[0-9a-f]{24}$ code: description: LogitrailService canonical code (e.g. `POSTIPAKETTI`). Used as fallback when id is absent. Resolved against the logitrail-service-catalog at write time. type: string minLength: 1 additionalProperties: false - type: "null" delivery_service: description: Select the actual LogitrailService by id (preferred) or code. null clears the field. anyOf: - type: object properties: id: description: LogitrailService ObjectId. Takes precedence over code when both are present. type: string pattern: ^[0-9a-f]{24}$ code: description: LogitrailService canonical code. Used as fallback when id is absent. type: string minLength: 1 additionalProperties: false - type: "null" requested_pickup_point: description: Raw pickup-point hint. null clears requestedPickupPointCode/Info. anyOf: - type: object properties: code: type: string minLength: 1 info: anyOf: - type: string - type: "null" required: - code additionalProperties: false - type: "null" pickup_point: description: Select the resolved PickupPoint by id. null clears the field. anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: PickupPoint Mongo ObjectId (24 hex chars). Resolved against the pickup-point-service collection at write time. required: - id additionalProperties: false - type: "null" requested_delivery_destination: description: "@deprecated Use pickup_point instead. Equivalent to pickup_point: { id }; pickup_point wins if both are present." anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: PickupPoint Mongo ObjectId (24 hex chars). Resolved against the pickup-point-service collection at write time. required: - id additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" required: - order responses: "200": description: Updated order content: application/json: schema: type: object properties: order: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" additionalProperties: false our_id: anyOf: - type: string - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" status: type: string enum: - draft - passive - confirmed - waiting_products - problem - processing - processed - returning - returned - cancelled - deleted anonymized: description: Present (with `ts`) once the order has been anonymized — indicates customer fields have been wiped. Null/absent otherwise. 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))$ description: Timestamp when anonymization was applied. required: - ts additionalProperties: false description: Present when the order has been anonymized. Absent otherwise. - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" process_hold: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" items: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Order line stable identifier (24-hex Mongo ObjectId). Used as the path parameter on the per-item PATCH endpoint. product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string minLength: 1 sku: type: string minLength: 1 components: description: Component/sub-product breakdown when this order line's product is a bundle. Omitted for non-bundle lines. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: description: Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: "null" required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: Amount of this sub-product included per unit of the order line's product. required: - product - amount additionalProperties: false - type: "null" required: - id - name - sku additionalProperties: false fulfillment_by: type: string enum: - logitrail - merchant title: Fulfillment route description: Fulfillment route for this order line. `logitrail` means Logitrail's warehouse picks and ships the line; `merchant` means the merchant fulfills it themselves and Logitrail does not pick or ship it. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency additionalProperties: false - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Up to 2000 characters. Omitted when no note has been recorded. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 required: - id - product - fulfillment_by - quantity additionalProperties: false created_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 (ISO 8601) when the order was created in Logitrail. merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system, if provided by the merchant. no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. requested_delivery_method: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" mapping_status: anyOf: - type: string - type: "null" required: - code - info - mapping_status additionalProperties: false - type: "null" description: Raw delivery-method hint from the inbound channel (code + free-text info + mapping status). Null when not set. requested_delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The LogitrailService selected as the requested delivery method. Null when not set or not yet resolved. delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The actual LogitrailService used for fulfilment. Null when not set. requested_pickup_point: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" required: - code - info additionalProperties: false - type: "null" description: Raw pickup-point hint (code + free-text info). Null when not set. pickup_point: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false - type: "null" description: The resolved PickupPoint entity. Null when not set or not yet resolved. requested_delivery_destination: anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" description: "@deprecated Use pickup_point instead. Kept for backwards compatibility — mirrors pickup_point on read." extra_services: description: LogitrailService attachments on this order. 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 required: - id - customer - our_id - status - items - created_at additionalProperties: false required: - order 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 delete: summary: Delete or cancel order description: "Removes an order from active processing. Maps `draft → deleted`; maps `confirmed`, `waiting_products`, `problem`, and `passive` → `cancelled`. Idempotent: already-deleted or already-cancelled orders return 204. Returns 409 for any other current status." operationId: DeleteOrder security: - idp: - orders: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: Order deleted or cancelled. "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: Order not found. content: application/json: {} "409": description: Order is in a status that does not permit deletion or cancellation. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string description: Reason of the error. required: - message - error_code additionalProperties: false /v1/orders/statistics: get: summary: Get merchant order statistics description: Returns order statistics for a merchant. operationId: GetMerchantStatistics security: - idp: - orders: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: Order statistics content: application/json: {} "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/orders/statistics/kpis: get: summary: Get order statistics KPIs description: Returns aggregated order KPIs for the authenticated merchant. Supports flexible grouping and date filtering. operationId: GetOrderStatisticsKpis security: - idp: - orders: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 created_at filter (inclusive). ISO 8601 datetime or YYYY-MM-DD. type: string description: Minimum created_at filter (inclusive). ISO 8601 datetime or YYYY-MM-DD. - in: query name: created_at_max schema: description: Maximum created_at filter (inclusive). ISO 8601 datetime or YYYY-MM-DD. type: string description: Maximum created_at filter (inclusive). ISO 8601 datetime or YYYY-MM-DD. - in: query name: status schema: description: Comma-separated order statuses to filter by. type: string description: Comma-separated order statuses to filter by. - in: query name: group_by schema: description: "Comma-separated dimensions: status, customer.country_code, created_at_date." type: string description: "Comma-separated dimensions: status, customer.country_code, created_at_date." - in: query name: kpis schema: description: "Comma-separated KPIs: order_count, line_items_per_order, total_quantity. Default: order_count." type: string description: "Comma-separated KPIs: order_count, line_items_per_order, total_quantity. Default: order_count." responses: "200": description: Order statistics KPIs content: application/json: schema: type: object properties: statistics: type: object properties: query: type: object properties: created_at_min: type: string created_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. kpis: type: object propertyNames: type: string additionalProperties: type: number description: KPI name to numeric value mapping. 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. required: - kpis additionalProperties: false description: Aggregate totals across all result rows. required: - query - results - totals additionalProperties: false required: - 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/orders/waiting-products: get: summary: Get waiting products in orders description: Returns products waiting for stock across the merchant's orders. Per-row `by_status` breakdown surfaces whether the article counts are demand placeholders, in-flight inbound shipments, or quarantined incidents. operationId: GetWaitingProducts security: - idp: - orders: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: Waiting products content: application/json: {} "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/orders/waiting_products: get: summary: Get waiting products in orders (deprecated underscore alias) description: Deprecated alias for `GET /v1/orders/waiting-products`. Move to the kebab-case URL; the underscore form remains available until its sunset on 2026-11-20. operationId: GetWaitingProductsInOrders security: - idp: - orders:read deprecated: true x-deprecation: deprecated_at: 2026-05-20 reason: Path renamed to kebab-case for URL convention consistency across the API surface. replacement_path: /v1/orders/waiting-products x-sunset: 2026-11-20 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: Waiting products content: application/json: {} "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/orders/{orderId}/items/{itemId}: patch: summary: Patch order item description: Updates `best_before_date` and/or `batch_numbers` on a single order item line. Both fields support null to clear. Returns the full updated order DTO. 404 when order/item is not found for the calling merchant. operationId: PatchOrderItem security: - idp: - orders: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: 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" additionalProperties: false responses: "200": description: Updated order content: application/json: schema: type: object properties: order: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" additionalProperties: false our_id: anyOf: - type: string - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" status: type: string enum: - draft - passive - confirmed - waiting_products - problem - processing - processed - returning - returned - cancelled - deleted anonymized: description: Present (with `ts`) once the order has been anonymized — indicates customer fields have been wiped. Null/absent otherwise. 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))$ description: Timestamp when anonymization was applied. required: - ts additionalProperties: false description: Present when the order has been anonymized. Absent otherwise. - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" process_hold: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" items: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Order line stable identifier (24-hex Mongo ObjectId). Used as the path parameter on the per-item PATCH endpoint. product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string minLength: 1 sku: type: string minLength: 1 components: description: Component/sub-product breakdown when this order line's product is a bundle. Omitted for non-bundle lines. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: description: Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: "null" required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: Amount of this sub-product included per unit of the order line's product. required: - product - amount additionalProperties: false - type: "null" required: - id - name - sku additionalProperties: false fulfillment_by: type: string enum: - logitrail - merchant title: Fulfillment route description: Fulfillment route for this order line. `logitrail` means Logitrail's warehouse picks and ships the line; `merchant` means the merchant fulfills it themselves and Logitrail does not pick or ship it. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency additionalProperties: false - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Up to 2000 characters. Omitted when no note has been recorded. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 required: - id - product - fulfillment_by - quantity additionalProperties: false created_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 (ISO 8601) when the order was created in Logitrail. merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system, if provided by the merchant. no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. requested_delivery_method: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" mapping_status: anyOf: - type: string - type: "null" required: - code - info - mapping_status additionalProperties: false - type: "null" description: Raw delivery-method hint from the inbound channel (code + free-text info + mapping status). Null when not set. requested_delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The LogitrailService selected as the requested delivery method. Null when not set or not yet resolved. delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The actual LogitrailService used for fulfilment. Null when not set. requested_pickup_point: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" required: - code - info additionalProperties: false - type: "null" description: Raw pickup-point hint (code + free-text info). Null when not set. pickup_point: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false - type: "null" description: The resolved PickupPoint entity. Null when not set or not yet resolved. requested_delivery_destination: anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" description: "@deprecated Use pickup_point instead. Kept for backwards compatibility — mirrors pickup_point on read." extra_services: description: LogitrailService attachments on this order. 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 required: - id - customer - our_id - status - items - created_at additionalProperties: false required: - order 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: Order or item not found content: application/json: {} /v1/orders/{orderId}/extra_services: post: summary: Attach a LogitrailService to an order as a whole description: Attaches a service that operates at order scope (e.g. gift wrap, fragile-handling surcharge, expedited fulfilment) to an order. The service is identified by `id` or `code`; the server resolves the catalog row, verifies the service is enabled, applicable to order scope, and available to the requesting merchant. NOT used for the order delivery method — that is the dedicated `requested_delivery_service` field on the order. operationId: AttachServiceToOrder security: - idp: - orders: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 order 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: Order 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/orders/{orderId}/items/{itemId}/extra_services: post: summary: Attach a LogitrailService to an order line item description: Attaches a service that operates at order-line-item scope (e.g. per-unit assembly, per-unit warranty, per-unit gift wrap) to a specific line item on an order. The service is identified by `id` or `code`; the server resolves the catalog row, verifies the service is enabled, applicable to order-item scope, and available to the requesting merchant. operationId: AttachServiceToOrderItem security: - idp: - orders: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 order 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: Order, 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/orders/{orderId}/_confirm: post: summary: Confirm order description: "Transitions a `draft` order to `confirmed`. Idempotent: an already-confirmed order returns 200. Returns 409 if the order is in any other status, and 422 with `error_code: ORDER_STATUS_GATE_NO_LINE_ITEMS` if the draft has no line items." operationId: ConfirmOrder security: - idp: - orders: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: reason: description: Optional free-form reason stored on the audit stamp. type: string minLength: 1 maxLength: 200 responses: "200": description: Order confirmed (or already confirmed). content: application/json: schema: type: object properties: order: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" additionalProperties: false our_id: anyOf: - type: string - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" status: type: string enum: - draft - passive - confirmed - waiting_products - problem - processing - processed - returning - returned - cancelled - deleted anonymized: description: Present (with `ts`) once the order has been anonymized — indicates customer fields have been wiped. Null/absent otherwise. 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))$ description: Timestamp when anonymization was applied. required: - ts additionalProperties: false description: Present when the order has been anonymized. Absent otherwise. - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" process_hold: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" items: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Order line stable identifier (24-hex Mongo ObjectId). Used as the path parameter on the per-item PATCH endpoint. product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string minLength: 1 sku: type: string minLength: 1 components: description: Component/sub-product breakdown when this order line's product is a bundle. Omitted for non-bundle lines. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: description: Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: "null" required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: Amount of this sub-product included per unit of the order line's product. required: - product - amount additionalProperties: false - type: "null" required: - id - name - sku additionalProperties: false fulfillment_by: type: string enum: - logitrail - merchant title: Fulfillment route description: Fulfillment route for this order line. `logitrail` means Logitrail's warehouse picks and ships the line; `merchant` means the merchant fulfills it themselves and Logitrail does not pick or ship it. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency additionalProperties: false - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Up to 2000 characters. Omitted when no note has been recorded. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 required: - id - product - fulfillment_by - quantity additionalProperties: false created_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 (ISO 8601) when the order was created in Logitrail. merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system, if provided by the merchant. no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. requested_delivery_method: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" mapping_status: anyOf: - type: string - type: "null" required: - code - info - mapping_status additionalProperties: false - type: "null" description: Raw delivery-method hint from the inbound channel (code + free-text info + mapping status). Null when not set. requested_delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The LogitrailService selected as the requested delivery method. Null when not set or not yet resolved. delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The actual LogitrailService used for fulfilment. Null when not set. requested_pickup_point: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" required: - code - info additionalProperties: false - type: "null" description: Raw pickup-point hint (code + free-text info). Null when not set. pickup_point: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false - type: "null" description: The resolved PickupPoint entity. Null when not set or not yet resolved. requested_delivery_destination: anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" description: "@deprecated Use pickup_point instead. Kept for backwards compatibility — mirrors pickup_point on read." extra_services: description: LogitrailService attachments on this order. 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 required: - id - customer - our_id - status - items - created_at additionalProperties: false required: - order 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: Order not found. content: application/json: {} "409": description: Order is not in `draft` status; cannot transition to `confirmed`. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string description: Reason of the error. required: - message - error_code additionalProperties: false "422": description: Gate denied transition (e.g. order has no line items). content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string description: Reason of the error. required: - message - error_code additionalProperties: false /v1/orders/{orderId}/_passivate: post: summary: Passivate order description: "Transitions an actively reserving order (`confirmed`, `waiting_products` or `problem`) to `passive`, releasing all warehouse-side article reservations without losing the order or its line items. Use this to park an order that should not be picked right now but may be re-activated later by calling `_confirm` again. Idempotent: an already-passive order returns 200. Returns 409 from any other status (e.g. `draft`, `processing`, `cancelled`, `deleted`)." operationId: PassivateOrder security: - idp: - orders: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: reason: description: Optional free-form reason stored on the audit stamp. type: string minLength: 1 maxLength: 200 responses: "200": description: Order passivated (or already passive). content: application/json: schema: type: object properties: order: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" additionalProperties: false our_id: anyOf: - type: string - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" status: type: string enum: - draft - passive - confirmed - waiting_products - problem - processing - processed - returning - returned - cancelled - deleted anonymized: description: Present (with `ts`) once the order has been anonymized — indicates customer fields have been wiped. Null/absent otherwise. 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))$ description: Timestamp when anonymization was applied. required: - ts additionalProperties: false description: Present when the order has been anonymized. Absent otherwise. - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" process_hold: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" items: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Order line stable identifier (24-hex Mongo ObjectId). Used as the path parameter on the per-item PATCH endpoint. product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string minLength: 1 sku: type: string minLength: 1 components: description: Component/sub-product breakdown when this order line's product is a bundle. Omitted for non-bundle lines. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: description: Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: "null" required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: Amount of this sub-product included per unit of the order line's product. required: - product - amount additionalProperties: false - type: "null" required: - id - name - sku additionalProperties: false fulfillment_by: type: string enum: - logitrail - merchant title: Fulfillment route description: Fulfillment route for this order line. `logitrail` means Logitrail's warehouse picks and ships the line; `merchant` means the merchant fulfills it themselves and Logitrail does not pick or ship it. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency additionalProperties: false - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Up to 2000 characters. Omitted when no note has been recorded. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 required: - id - product - fulfillment_by - quantity additionalProperties: false created_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 (ISO 8601) when the order was created in Logitrail. merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system, if provided by the merchant. no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. requested_delivery_method: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" mapping_status: anyOf: - type: string - type: "null" required: - code - info - mapping_status additionalProperties: false - type: "null" description: Raw delivery-method hint from the inbound channel (code + free-text info + mapping status). Null when not set. requested_delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The LogitrailService selected as the requested delivery method. Null when not set or not yet resolved. delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The actual LogitrailService used for fulfilment. Null when not set. requested_pickup_point: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" required: - code - info additionalProperties: false - type: "null" description: Raw pickup-point hint (code + free-text info). Null when not set. pickup_point: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false - type: "null" description: The resolved PickupPoint entity. Null when not set or not yet resolved. requested_delivery_destination: anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" description: "@deprecated Use pickup_point instead. Kept for backwards compatibility — mirrors pickup_point on read." extra_services: description: LogitrailService attachments on this order. 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 required: - id - customer - our_id - status - items - created_at additionalProperties: false required: - order 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: Order not found. content: application/json: {} "409": description: Order is not in a status from which it can transition to `passive`. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string description: Reason of the error. required: - message - error_code additionalProperties: false "422": description: Gate denied transition. content: application/json: schema: type: object properties: message: type: string description: A brief, human readable error message. error_code: type: string description: Reason of the error. required: - message - error_code additionalProperties: false /v1/orders/by_our_id/{ourId}: get: summary: Get order by Logitrail ID description: Returns a single merchant order by its Logitrail-issued ID (`our_id`, e.g. `T1234ABCD`). Returns 404 if no order with that ID exists for the calling merchant. operationId: GetOrderByOurId security: - idp: - orders: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: Order details content: application/json: schema: type: object properties: order: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ customer: default: first_name: null last_name: null email: null phone: null organization: null address: null postal_code: null state: null city: null country_code: null vat_id: null eori: null door_code: null delivery_instructions: null type: object properties: first_name: anyOf: - type: string minLength: 1 - type: "null" last_name: anyOf: - type: string minLength: 1 - type: "null" email: anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" phone: anyOf: - type: string pattern: ^(\+[1-9]|[0-9])[0-9]+$ - type: "null" organization: anyOf: - type: string minLength: 1 - type: "null" address: anyOf: - type: string minLength: 1 - type: "null" postal_code: anyOf: - type: string minLength: 1 - type: "null" state: anyOf: - type: string minLength: 1 - type: "null" city: anyOf: - type: string minLength: 1 - type: "null" country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: "null" vat_id: anyOf: - type: string pattern: ^[A-Z]{2}[0-9A-Z]+$ - type: "null" eori: anyOf: - type: string minLength: 1 - type: "null" door_code: anyOf: - type: string minLength: 1 - type: "null" delivery_instructions: anyOf: - type: string minLength: 1 - type: "null" additionalProperties: false our_id: anyOf: - type: string - type: "null" merchants_id: anyOf: - type: string minLength: 1 - type: "null" status: type: string enum: - draft - passive - confirmed - waiting_products - problem - processing - processed - returning - returned - cancelled - deleted anonymized: description: Present (with `ts`) once the order has been anonymized — indicates customer fields have been wiped. Null/absent otherwise. 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))$ description: Timestamp when anonymization was applied. required: - ts additionalProperties: false description: Present when the order has been anonymized. Absent otherwise. - type: "null" process_lock: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" process_hold: anyOf: - type: object properties: id: anyOf: - type: string - type: "null" comment: anyOf: - type: string - type: "null" created: type: object properties: ts: 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" required: - ts additionalProperties: false expires: 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" required: - id - comment - created - expires additionalProperties: false - type: "null" items: type: array items: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ description: Order line stable identifier (24-hex Mongo ObjectId). Used as the path parameter on the per-item PATCH endpoint. product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string minLength: 1 sku: type: string minLength: 1 components: description: Component/sub-product breakdown when this order line's product is a bundle. Omitted for non-bundle lines. anyOf: - type: array items: type: object properties: product: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: description: Name of the sub-product in its merchant's primary language. Embedded for display convenience; omitted if the sub-product cannot be resolved. type: string sku: description: SKU of the sub-product. Null when the sub-product has no SKU; omitted if the sub-product cannot be resolved. anyOf: - type: string - type: "null" required: - id additionalProperties: false description: Reference to the sub-product. amount: type: integer minimum: 1 maximum: 9007199254740991 description: Amount of this sub-product included per unit of the order line's product. required: - product - amount additionalProperties: false - type: "null" required: - id - name - sku additionalProperties: false fulfillment_by: type: string enum: - logitrail - merchant title: Fulfillment route description: Fulfillment route for this order line. `logitrail` means Logitrail's warehouse picks and ships the line; `merchant` means the merchant fulfills it themselves and Logitrail does not pick or ship it. quantity: type: number minimum: 1 sales_info: anyOf: - type: object properties: gross_price: anyOf: - type: number - type: "null" description: Per-unit gross price of the order line, VAT included. Stored rounded to two decimals. tax_percent: anyOf: - type: number minimum: 0 maximum: 100 - type: "null" description: VAT rate that applies to the order line, expressed as a percent number (e.g. 24, 14, 10, 0). Values between 0 and 100 inclusive; up to two decimal places accepted (e.g. 25.5, 24.00). currency: anyOf: - type: string pattern: ^[A-Z]{3}$ - type: "null" description: ISO 4217 currency code for the gross price (e.g. EUR). 3 uppercase letters. Defaults to EUR when omitted. required: - gross_price - tax_percent - currency additionalProperties: false - type: "null" description: "Pricing information for the order line: gross unit price, VAT percent rate, and currency. Omitted when no pricing has been recorded." additional_info: anyOf: - type: string maxLength: 2000 - type: "null" description: Free-form merchant note attached to the order line. Up to 2000 characters. Omitted when no note has been recorded. 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])))$ description: Best-before date restriction for the order line, ISO 8601 (`YYYY-MM-DD`). The warehouse must pick articles whose shelf-life expiry equals this date. Omit to clear the restriction. - type: "null" batch_numbers: anyOf: - minItems: 1 type: array items: type: string minLength: 1 description: Batch numbers acceptable for fulfilling this order line. Articles whose batch is in this set may be picked. Omit (or send an empty array via PATCH `null`) to clear. - type: "null" extra_services: description: LogitrailService attachments on this order line. 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 required: - id - product - fulfillment_by - quantity additionalProperties: false created_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 (ISO 8601) when the order was created in Logitrail. merchants_order_time: 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: Timestamp (ISO 8601) of when the order was placed in the merchant's own system, if provided by the merchant. no_earlier_than: 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: Earliest time at which this order may be dispatched. Null means no lower bound. no_after_than: 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: Latest time by which this order must be dispatched. Null means no upper bound. language: anyOf: - type: string pattern: ^[a-z]{2}$ - type: "null" description: ISO 639-1 two-letter language code for the order (e.g. "fi", "sv", "en"). Drives communication language for order confirmations and notifications. Null means not specified. requested_delivery_method: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" mapping_status: anyOf: - type: string - type: "null" required: - code - info - mapping_status additionalProperties: false - type: "null" description: Raw delivery-method hint from the inbound channel (code + free-text info + mapping status). Null when not set. requested_delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The LogitrailService selected as the requested delivery method. Null when not set or not yet resolved. delivery_service: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ code: type: string name: type: string required: - id - name additionalProperties: false - type: "null" description: The actual LogitrailService used for fulfilment. Null when not set. requested_pickup_point: anyOf: - type: object properties: code: type: string info: anyOf: - type: string - type: "null" required: - code - info additionalProperties: false - type: "null" description: Raw pickup-point hint (code + free-text info). Null when not set. pickup_point: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false - type: "null" description: The resolved PickupPoint entity. Null when not set or not yet resolved. requested_delivery_destination: anyOf: - type: object properties: pickup_point: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ name: type: string required: - id - name additionalProperties: false required: - pickup_point additionalProperties: false - type: "null" description: "@deprecated Use pickup_point instead. Kept for backwards compatibility — mirrors pickup_point on read." extra_services: description: LogitrailService attachments on this order. 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 required: - id - customer - our_id - status - items - created_at additionalProperties: false required: - order 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: Order not found content: application/json: {} components: securitySchemes: idp: type: oauth2 flows: clientCredentials: tokenUrl: https://idp.logitrail.com/realms/logitrail/protocol/openid-connect/token scopes: orders:read: Read order data orders:manage: Manage order data