Skip to main content
API docs by Redocly

Inbound Shipment Management Service ((dev))

Download OpenAPI specification:Download

API for managing inbound shipments and their extra items.

List Inbound Shipments

Lists inbound shipments, optionally filtered by merchant, status, the quick_filter=open group shortcut, the merchant's reference (merchants_ref), a creation-date range (created_at_min/created_at_max), an estimated-arrival-date range (estimated_arrival_date_min/estimated_arrival_date_max), an originating order via original_order_id, a contained product via has_product_id, or a free-form q search across sender name, merchants_ref, and Logitrail ID.

Authorizations:
idp
query Parameters
merchant
string
Example: merchant=testmerchant.logitrail.com

Owning merchant

status
string (Status of the inbound shipment.)
Enum: "initial" "confirmed" "en_route" "arrived_at_warehouse" "processed" "processing" "problem" "cancelled" "deleted"

The current status of the inbound shipment. This is a read-only property.

q
string non-empty
Example: q=Acme

Free-form single-field search. Matches our_id and merchants_ref as case-insensitive prefixes; matches sender_name as a case-insensitive substring when the query is at least 3 characters long.

merchants_ref
string non-empty
Example: merchants_ref=PO-2026-001

Filter by the merchant's reference (exact match) on the inbound shipment.

string or string
Example: created_at_min=2026-04-01

Inclusive lower bound on the inbound shipment creation timestamp. Accepts YYYY-MM-DD (interpreted as start-of-day UTC) or a full ISO 8601 datetime.

string or string
Example: created_at_max=2026-04-30T23:59:59Z

Inclusive upper bound on the inbound shipment creation timestamp. Accepts YYYY-MM-DD (interpreted as end-of-day UTC) or a full ISO 8601 datetime.

estimated_arrival_date_min
string <date> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...
Example: estimated_arrival_date_min=2026-05-01

Inclusive lower bound on the inbound shipment estimated_arrival_date (YYYY-MM-DD). Shipments whose estimated_arrival_date is null are excluded when this bound is supplied.

estimated_arrival_date_max
string <date> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...
Example: estimated_arrival_date_max=2026-05-31

Inclusive upper bound on the inbound shipment estimated_arrival_date (YYYY-MM-DD). Shipments whose estimated_arrival_date is null are excluded when this bound is supplied.

original_order_id
string^[a-f0-9]{24}$
Example: original_order_id=6585aa3e6629101641191794

Returns only shipments where at least one line item references the given order via items[].original_order.id. 24-character hex MongoDB ObjectId. Useful for finding the order-return inbound shipment(s) that arose from a specific customer order.

has_product_id
string^[a-f0-9]{24}$
Example: has_product_id=662a66fac1a9fa33f20f9702

Returns only shipments where at least one line item references the given product via items[].product.id. 24-character hex MongoDB ObjectId. Mirrors the has_product_id filter on ListOrders.

quick_filter
string
Value: "open"
Example: quick_filter=open

Status group shortcut. open matches shipments in initial, confirmed, processing, arrived_at_warehouse, or problem status. Ignored when status is also given.

limit
number [ 1 .. 1000 ]
Default: 250

Responses

Response samples

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

Create Inbound Shipment

Creates a new inbound shipment in the initial status for the merchant.

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

Logitrail's Merchant ID.

Responses

Response samples

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

Get Inbound Shipment Statistics

Returns per-status counts of the merchant inbound shipments.

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

Logitrail's Merchant ID.

Responses

Response samples

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

Get Product Arrival Estimations

Returns arrival estimations for a single product across open inbound shipments of the merchant.

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

Logitrail's Merchant ID.

Responses

Response samples

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

Get Inbound Shipment

Returns the full DTO of a single inbound shipment.

Authorizations:
idp

Responses

Response samples

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

Update Inbound Shipment

Partially updates an inbound shipment. Only fields present in the request body are modified; omitted fields are left unchanged. Updating items replaces the full item list. Returns 409 if the shipment is in a status that no longer allows edits (arrived_at_warehouse, processing, processed, problem, cancelled, or deleted).

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

Logitrail's Merchant ID.

Request Body schema: application/json
required
object

Inbound Shipment Data for Update

string or null

Merchant's reference to the inbound shipment. Note that value is trimmed (trailing and leading spaces removed) and empty string is ignored.

string or null

Sender's name, as given by the merchant.

number or null

Merchant's priority of the inbound shipment. This can be an integer between -10000000 (slowest handling) to 1000000 (fastest handling). Note that the value is effective only within merchant's other inbound shipments. Value 0 is ignored.

string or null

Free text remarks from Merchant to Logitrail.

string or null

Estimated arrival date of the inbound shipment.

Array of objects

List of product items to be expected to arrive in this inbound shipment. Note that passing this argument replaces the item list. If you want to add or remove individual item, use /products endpoint.

Responses

Request samples

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

Response samples

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

Cancel Inbound Shipment

Cancels an inbound shipment, transitioning it to the cancelled status. Returns 409 if the shipment is already being processed at the warehouse (arrived_at_warehouse or processing status).

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

Logitrail's Merchant ID.

Responses

Response samples

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

Update a single inbound shipment line item

Partially updates a single line item by its item_id. Only the supplied fields are modified; omitted fields are left unchanged. Use this endpoint instead of the full-shipment PATCH when editing one item to avoid race conditions with concurrent updates to other items.

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

Logitrail's Merchant ID.

Request Body schema: application/json
required
object

Fields to update on the line item.

quantity
number >= 1

Expected quantity to arrive. Must be ≥ 1.

number or null

Declared purchase price per unit. Pass null to clear an existing value.

string or null

ISO 4217 currency code for unit_purchase_price (e.g. "EUR"). Pass null to clear.

object or null

For order-return inbound shipments: the originating sales order. Pass null to clear.

Responses

Request samples

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

Response samples

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

Delete a line item from an inbound shipment

Removes a single line item by its item_id. Returns 409 if the shipment status no longer allows edits, or if the item already has units arrived in the warehouse.

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": [
    ]
}

Add a line item to an inbound shipment

Appends a single new line item to the shipment. Returns 409 if the shipment status no longer allows edits.

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

Logitrail's Merchant ID.

Request Body schema: application/json
required
object

The line item to add to the shipment.

required
object
quantity
required
number >= 1

Expected quantity to arrive

number or null

Declared purchase price per unit for this line item. Optional. Pass null to clear an existing value.

string or null

ISO 4217 currency code for unit_purchase_price (e.g. "EUR", "USD"). Optional. Pass null to clear.

object or null

For order-return inbound shipments: reference to the original order from which the returned product originated. Must belong to the requesting merchant. Pass null to clear an existing reference; omit to leave it unchanged.

Responses

Request samples

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

Response samples

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

Attach a LogitrailService to an inbound shipment as a whole

Attaches a service that operates at shipment scope (e.g. arrival inspection, full-pallet handling, or any service with applicable_scopes covering inbound_shipment) to an inbound shipment. The service is identified by id or code; the server resolves the catalog row, verifies the service is enabled, applicable to inbound-shipment scope, and available to the requesting merchant.

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 inbound shipment 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 inbound shipment line item

Attaches one or more services (assembly, labelling, inspection, special packaging, etc.) to a specific line item on an inbound shipment. The service is identified by id or code; the server resolves the catalog row, verifies the service is enabled, applicable to inbound-shipment-item scope, and available to the requesting merchant. The attachment is recorded with quantity, optional service-specific parameters, optional merchant remarks, and a server-generated created stamp.

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 inbound shipment 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": {
    }
}

Update Extra Item (merchants_decision only)

Applies the merchant's handling decision to an extra-item subdocument. Accepts only the merchants_decision envelope; the merchant may set code and/or merchant_remarks together or separately, but no other extra-item fields.

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

Logitrail's Merchant ID.

Request Body schema: application/json
required
object

Merchant-allowed extra-item updates. Only the merchants_decision envelope is settable; other fields require the internal endpoint.

required
object

Partial update of the merchant decision envelope. Provide code and/or merchant_remarks (at least one required).

code
string

Handling instruction code for Logitrail. Omit to leave the existing code unchanged.

merchant_remarks
string

Free-form remarks from the merchant to Logitrail. Omit to leave existing remarks unchanged.

Responses

Request samples

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

Response samples

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

Get Inbound Shipment Attachments

Returns the attachment list for a single inbound shipment with temporary download URLs valid for 30 minutes.

Authorizations:
idp

Responses

Response samples

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