Skip to main content
API docs by Redocly

Order Management Service ((dev))

Download OpenAPI specification:Download

API for Order Management.

Create order

Creates a new order for a merchant.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json
required
object
object
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}
string or null
object or null
boolean or null
Array of objects
string or null

Earliest time at which this order may be dispatched. Null means no lower bound.

string or null

Latest time by which this order must be dispatched. Null means no upper bound.

string or null

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.

string or null

Timestamp (ISO 8601) of when the order was placed in the merchant's own system. Stored on the order and returned on read.

object or null

Raw delivery-method hint. null clears requestedDeliveryMethodCode/Info.

object or null

Select the requested LogitrailService by code. null clears the field.

object or null

Select the actual LogitrailService by id (preferred) or code. null clears the field.

object or null

Raw pickup-point hint. null clears requestedPickupPointCode/Info.

object or null

Select the resolved PickupPoint by id. null clears the field.

object or null

@deprecated Use pickup_point instead. Equivalent to pickup_point: { id }; pickup_point wins if both are present.

status
string
Enum: "draft" "confirmed"

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.

Responses

Request samples

Content type
application/json
{
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

List orders

Returns a paginated list of merchant orders. Multiple filters may be combined; they are AND-merged in the resulting query.

Authorizations:
idp
query Parameters
status
string
Enum: "draft" "passive" "confirmed" "waiting_products" "problem" "processing" "processed" "returning" "returned" "cancelled" "deleted"

Exact match on order status. See OrderStatusEnum for the list of values.

has_product_id
string^[0-9a-f]{24}$

Filter orders that contain a line referencing this product (Mongo ObjectId, 24 hex chars).

our_id
string^T\d{4,}[A-Z0-9]{4}$

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).

merchants_id
string non-empty

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.

customer_name_search
string >= 3 characters

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.

q
string >= 3 characters

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 (substring, case-insensitive) across merchants_id and customer name fields.

quick_filter
string
Value: "open"

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].

offset
number >= 0
Default: 0

Pagination offset. Defaults to 0.

limit
number [ 1 .. 1000 ]
Default: 250

Maximum number of orders to return. Defaults to 250, capped at 1000.

header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Get order

Returns a merchant order by ID.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Responses

Response samples

Content type
application/json
{
  • "order": {
    }
}

Update order

Updates an existing merchant order.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json
required
object
object
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}
string or null
object or null
Array of objects
string or null

Earliest time at which this order may be dispatched. Null means no lower bound.

string or null

Latest time by which this order must be dispatched. Null means no upper bound.

string or null

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.

string or null

Timestamp (ISO 8601) of when the order was placed in the merchant's own system. Stored on the order and returned on read.

object or null

Raw delivery-method hint. null clears requestedDeliveryMethodCode/Info.

object or null

Select the requested LogitrailService by code. null clears the field.

object or null

Select the actual LogitrailService by id (preferred) or code. null clears the field.

object or null

Raw pickup-point hint. null clears requestedPickupPointCode/Info.

object or null

Select the resolved PickupPoint by id. null clears the field.

object or null

@deprecated Use pickup_point instead. Equivalent to pickup_point: { id }; pickup_point wins if both are present.

Responses

Request samples

Content type
application/json
{
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Delete or cancel order

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.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "error_code": "VALIDATION_ERROR",
  • "validation_errors": [
    ]
}

Get merchant order statistics

Returns order statistics for a merchant.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "error_code": "VALIDATION_ERROR",
  • "validation_errors": [
    ]
}

Get order statistics KPIs

Returns aggregated order KPIs for the authenticated merchant. Supports flexible grouping and date filtering.

Authorizations:
idp
query Parameters
created_at_min
string

Minimum created_at filter (inclusive). ISO 8601 datetime or YYYY-MM-DD.

created_at_max
string

Maximum created_at filter (inclusive). ISO 8601 datetime or YYYY-MM-DD.

status
string

Comma-separated order statuses to filter by.

group_by
string

Comma-separated dimensions: status, customer.country_code, created_at_date.

kpis
string

Comma-separated KPIs: order_count, line_items_per_order, total_quantity. Default: order_count.

header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Responses

Response samples

Content type
application/json
{
  • "statistics": {
    }
}

Get waiting products in orders

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.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "error_code": "VALIDATION_ERROR",
  • "validation_errors": [
    ]
}

Get waiting products in orders (deprecated underscore alias) Deprecated

Deprecated alias for GET /v1/orders/waiting-products. Move to the kebab-case URL; the underscore form remains until its sunset on 2026-11-20 per the DEV-1137 deprecation programme.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "error_code": "VALIDATION_ERROR",
  • "validation_errors": [
    ]
}

Patch order item

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.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json
string or null
Array of strings or null

Responses

Request samples

Content type
application/json
{
  • "best_before_date": "2019-08-24",
  • "batch_numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Attach a LogitrailService to an order as a whole

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.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json
required
object

Service attachment to add to the order as a whole. Provide the service reference by id or code; the server resolves the other.

required
object

Service to attach. Provide either id or code; the server resolves the other.

quantity
integer [ 1 .. 9007199254740991 ]

Optional per-attachment quantity.

object

Service-specific extras. Validated against the per-service Zod schema (when registered) at attach time.

merchant_remarks
string

Public free-form remarks from the merchant.

Responses

Request samples

Content type
application/json
{
  • "service_attachment": {
    }
}

Response samples

Content type
application/json
{
  • "service_attachment": {
    }
}

Attach a LogitrailService to an order line item

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.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json
required
object

Service attachment to add to the order line item. Provide the service reference by id or code; the server resolves the other.

required
object

Service to attach. Provide either id or code; the server resolves the other.

quantity
integer [ 1 .. 9007199254740991 ]

Optional per-attachment quantity.

object

Service-specific extras. Validated against the per-service Zod schema (when registered) at attach time.

merchant_remarks
string

Public free-form remarks from the merchant.

Responses

Request samples

Content type
application/json
{
  • "service_attachment": {
    }
}

Response samples

Content type
application/json
{
  • "service_attachment": {
    }
}

Confirm order

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.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json
reason
string [ 1 .. 200 ] characters

Optional free-form reason stored on the audit stamp.

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Passivate order

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).

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Request Body schema: application/json
reason
string [ 1 .. 200 ] characters

Optional free-form reason stored on the audit stamp.

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Get order by Logitrail ID

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.

Authorizations:
idp
header Parameters
x-logitrail-merchant-id
required
string non-empty

Logitrail's Merchant ID.

Responses

Response samples

Content type
application/json
{
  • "order": {
    }
}