Skip to main content
API docs by Redocly

Order Return Management Service ((dev))

Download OpenAPI specification:Download

API for managing customer and agent order returns.

Create New Order Return

Creates a new OrderReturn for the merchant in preinfo_received status. The supplied skeleton may be empty; line items, original-order references, and merchant remarks may be provided.

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

Logitrail's Merchant ID.

Request Body schema: application/json
required
object
string or null
Default: null

Name for the order return.

type
string
Default: "customer_return"
Enum: "agent_return" "customer_return"

The type of the return. customer_return = the customer initiated the return. agent_return = the agent (carrier/pickup point) initiated the return, the original recipient has not picked up the shipment.

string or null
Default: null
object or null

Reference to Logitrail's original order associated with this return.

string or null
Default: null

The merchant's own reference associated to this return.

string or null

Special handling instructions for Logitrail.

Array of objects

The items included in the return, if known. Omit if returned items are not known. In case original order is defined, items are fetched from the original order. Empty array sets the return empty (no items).

Array of objects
Default: []

Array of service references associated with this return.

Responses

Request samples

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

Response samples

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

List Order Returns

Returns a paginated list of the merchant order returns, newest first. Filters AND-merge; status accepts multiple values, and q searches the name, merchant reference and (for a 24-hex phrase) the return id. List items use a lean projection that omits the items and services collections carried by the detail endpoint.

Authorizations:
idp
query Parameters
status
Array of strings non-empty
Items Enum: "pending" "accepted" "resend_pending" "restocking_pending" "processing" "processed" "deleted" "preinfo_received" "pending_merchant_decision"
Example: status=pending,processing

Filter by status. Accepts a single value or a comma-separated / repeated list; results match any of the supplied statuses.

type
string
Enum: "agent_return" "customer_return"
Example: type=customer_return

Filter by return type.

q
string >= 2 characters

Free-form search phrase (minimum 2 characters). Matches a case-insensitive substring of the name or merchant reference; a 24-hex phrase additionally matches the return id.

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

Restrict results to returns linked to this original order id (Logitrail ObjectId, 24 hex chars).

offset
integer [ 0 .. 9007199254740991 ]
Default: 0

Pagination offset. Defaults to 0.

limit
integer [ 1 .. 500 ]
Default: 100

Maximum number of returns to return. Defaults to 100, capped at 500.

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

Logitrail's Merchant ID.

Responses

Response samples

Content type
application/json
{
  • "order_returns": [
    ],
  • "total": 9007199254740991
}

Get Order Return Details

Returns the full DTO of a single OrderReturn.

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

Logitrail's Merchant ID.

Responses

Response samples

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

Cancel Order Return

Cancels (soft-deletes) an OrderReturn early in its lifecycle, transitioning it to deleted. When the return has an inbound shipment linked, the inbound is cancelled in the same call; if the inbound is already being processed at the warehouse, the cancel is rejected with 409 and the return is left untouched. Only returns in pending / preinfo_received may be cancelled.

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

Logitrail's Merchant ID.

Responses

Response samples

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

Set Merchant Decision On Order Return

Sets the merchant's decision on how an order return should be handled when it arrives at the warehouse. When the decision is to_shelf and the return has no inbound shipment linked yet, a matching inbound shipment is auto-created from the return's items and back-linked atomically.

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

Logitrail's Merchant ID.

Request Body schema: application/json
required
object

The merchant's decision on how to handle the return.

code
required
string
Enum: "to_shelf" "shelf_for_disposal" "resend" "reject" "destroy"

Decision code indicating how the merchant wants the return handled when it arrives at the warehouse. When set to to_shelf and the return has no inbound shipment linked yet, a matching inbound is auto-created from the return's items.

Responses

Request samples

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

Response samples

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