Skip to main content
API docs by Redocly

Order Return Management Service (2026-08-17.2764666158)

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.

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.

Array of strings or null
Default: null

Carrier tracking codes for the return shipment, one entry per physical box (a return parcel can be multi-box). Set by Logitrail when the return label is created through the Logitrail API, or by the merchant when the label is created independently. Entries accumulate across label generations: regenerating a label appends its tracking code rather than replacing the list, so codes from superseded labels remain and the most recently issued code is last. Replace the whole array to prune it.

object or null
Default: null

Present when this return was force-closed to processed by an internal admin action outside the normal lifecycle, instead of null.

object or null
Default: null

Present when the warehouse destroyed this return's goods without waiting for a merchant decision, because the parcel arrived too damaged to shelve, resend or inspect (DEV-2704). Records who forced it and when. Deliberately distinct from a destroy merchant decision — that is the merchant's instruction, this is the warehouse overriding in its absence, and consumers should present the two differently. Null when no force-destroy has been performed.

required
object

The merchant's intended decision for handling the return when it arrives at the warehouse. Required at creation. May be replaced any time before release via the dedicated merchant-decision endpoint.

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, the merchant reference, the return's own reference (e.g. R1042X7K), or any of the return's own carrier tracking codes; a 24-hex phrase additionally matches the return id. Also matches the linked original order: its T-number (our_id), customer name, and the merchant's own order 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).

tracking_code
string non-empty
Example: tracking_code=JJFI123456789

Restrict results to the return carrying this carrier tracking code.

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

Inclusive lower bound on the order return 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 order return creation timestamp. Accepts YYYY-MM-DD (interpreted as end-of-day UTC) or a full ISO 8601 datetime.

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

Update Order Return

Partially updates an OrderReturn. Only the fields present in the request body are modified — omitted fields keep their current value. Supplying items replaces the full item list. System-managed fields (status, merchant decision, warehouse location, etc.) are not writable here. Only legal while the return hasn't started processing yet (the same window _merchant-decision uses); rejected with 409 once released for processing.

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

Logitrail's Merchant ID.

Request Body schema: application/json
required
object

Partial OrderReturn update. Only the fields present in the body are modified; omitted fields keep their current value. Supplying items replaces the full item list.

string or null

Name for the order return.

type
string
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

Free-form remarks.

object or null

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

string or null

The merchant's own reference associated to this return.

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.

Array of strings or null

Carrier tracking codes for the return shipment, one entry per physical box (a return parcel can be multi-box).

object or null
Default: null

Present when this return was force-closed to processed by an internal admin action outside the normal lifecycle, instead of null.

object or null
Default: null

Present when the warehouse destroyed this return's goods without waiting for a merchant decision, because the parcel arrived too damaged to shelve, resend or inspect (DEV-2704). Records who forced it and when. Deliberately distinct from a destroy merchant decision — that is the merchant's instruction, this is the warehouse overriding in its absence, and consumers should present the two differently. Null when no force-destroy has been performed.

string or null
Default: null

Who created this return: the merchant, or Logitrail on the merchant's behalf. Derived from the caller at creation time; never caller-suppliable. Null on returns created before this field existed — that means the origin is unknown, not that the return is merchant-originated.

Responses

Request samples

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

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

Records the merchant's two-level decision on how an order return should be handled: a whole-return code (resend_as_it_is, destroy, to_shelf, or resend_as_new) plus, optionally for to_shelf and resend_as_new, a per-line decision for any items that shouldn't follow the whole-return code's default disposition (to_shelf lines default to per-line to_shelf; resend_as_new lines default to per-line resend). This call is side-effect-free — it transitions the return to accepted but creates no artifacts. The warehouse releases the return for processing separately once ready to act on the decision; that step performs the actual processing automation (auto-creating the inbound shipment / resend order / outbound shipment).

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: "resend_as_it_is" "destroy" "to_shelf" "resend_as_new"

Whole-return decision indicating how the merchant wants the return handled: resend_as_it_is (unopened, re-shipped against the original order), destroy, to_shelf (shelved back into stock), or resend_as_new (per-line shelve/destroy plus a new order for resent lines). to_shelf and resend_as_new accept an optional per-line items decision for lines that shouldn't follow the whole-code default (to_shelf lines default to per-line to_shelf; resend_as_new lines default to per-line resend); resend_as_it_is and destroy take no items. Recording a decision does not release the return for processing — that happens on the separate release call. The decision (whole-return and per-line) may be sent again any time before release to replace what was recorded; each call fully replaces the previous per-line decisions rather than merging with them.

Array of objects

Per-line dispositions, for lines that shouldn't follow the whole-code default. Only meaningful when code is to_shelf or resend_as_new (omit otherwise) — omitting or only partially listing lines is fine, unlisted lines default per code (see the code field description).

Responses

Request samples

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

Response samples

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

Set Per-Item Merchant Decision On Order Return

Sets a single line item's per-line merchant decision. The whole-return decision must already be set. Only allowed for whole-codes that support per-line decisions (to_shelf, resend_as_new). This is a targeted update to one item's decision record, distinct from the batch merchant-decision endpoint.

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

Logitrail's Merchant ID.

Request Body schema: application/json
required
object

Per-line merchant decision. Must match the whole-return decision code rules. May be sent again any time before release to replace the previously recorded per-line decision for this item.

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

This line's disposition. resend is only legal when the whole-return decision is resend_as_new.

object

Replacement product to restock this line under instead of the original. Only legal alongside per-line to_shelf.

Responses

Request samples

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

Response samples

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

Attach a LogitrailService to a customer return as a whole

Attaches a service that operates at customer-return scope (e.g. inspection, repackaging, disposal handling) to a return as a whole. The service is identified by id or code; the server resolves the catalog row, verifies the service is enabled, applicable to customer-return scope, and available to the requesting merchant. Per-line-item return services are attached through a separate endpoint.

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 customer return 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 return line item

Attaches a service that operates at customer-return-item scope (e.g. per-item inspection, individual repackaging) to a single line item on a customer return. The service is identified by id or code; the server resolves the catalog row, verifies it is enabled, applicable to customer-return-item scope, and available to the requesting merchant. Return-as-a-whole services are attached through a separate endpoint.

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

Request a return label for an order return

Requests generation of a return-label PDF for the order return, or optionally a paperless label (e.g. a QR code sent directly to the end customer) instead, when the carrier supports it. Generation runs asynchronously (label provider → attachment storage), but this endpoint waits briefly for a fast result: if the label finishes generating within the wait_seconds window it returns 200 with the final state inline, otherwise it returns 202 Accepted — poll GET /v1/order-returns/{orderReturnId}/return-label for the status and download reference. Re-requesting while a label is already pending/processing gets the same wait-then-response treatment without starting duplicate work.

Authorizations:
idp
query Parameters
wait_seconds
integer [ 0 .. 10 ]
Default: 10
Example: wait_seconds=10

How long (seconds) to wait for the label to resolve before falling back to 202 Accepted. 0 skips the wait entirely and returns 202 immediately. Capped at 10.

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

Logitrail's Merchant ID.

Request Body schema: application/json
paperless
boolean

Request a paperless label instead of a printable PDF, when the carrier supports it. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "paperless": false
}

Response samples

Content type
application/json
{
  • "order_return_id": "64b8f0c2e1b2c3d4e5f67890",
  • "return_label": {
    }
}

Get return-label status and download reference

Returns the current return-label state for the order return. While generation is in flight the status is pending or processing (poll with backoff); once complete the attachment field carries the download reference. failed indicates generation could not be completed.

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

Logitrail's Merchant ID.

Responses

Response samples

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

List files attached to an order return

Returns the list of files (photos, PDFs) attached to the order return, each with its purpose, optional remarks, file metadata, and a short-lived download link resolved at read time.

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

Logitrail's Merchant ID.

Responses

Response samples

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

List files attached to an order return's line item

Returns the list of files (photos, PDFs) attached to a single line item on the order return, each with its purpose, optional remarks, file metadata, and a short-lived download link resolved at read time. Per-line-item sibling of the whole-return attachment list.

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

Logitrail's Merchant ID.

Responses

Response samples

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

Create an Order Return from an Order

Shortcut for creating an OrderReturn against a specific order without having to look up and copy its line items yourself. Omit items entirely to default to every one of the order's lines (a combo/package product is expanded into one return line per component); supply items to override the default. All other fields behave exactly as on POST /v1/order-returns.

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

Logitrail's Merchant ID.

Request Body schema: application/json
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.

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.

Array of strings or null
Default: null

Carrier tracking codes for the return shipment, one entry per physical box (a return parcel can be multi-box). Set by Logitrail when the return label is created through the Logitrail API, or by the merchant when the label is created independently. Entries accumulate across label generations: regenerating a label appends its tracking code rather than replacing the list, so codes from superseded labels remain and the most recently issued code is last. Replace the whole array to prune it.

object or null
Default: null

Present when this return was force-closed to processed by an internal admin action outside the normal lifecycle, instead of null.

object or null
Default: null

Present when the warehouse destroyed this return's goods without waiting for a merchant decision, because the parcel arrived too damaged to shelve, resend or inspect (DEV-2704). Records who forced it and when. Deliberately distinct from a destroy merchant decision — that is the merchant's instruction, this is the warehouse overriding in its absence, and consumers should present the two differently. Null when no force-destroy has been performed.

required
object

The merchant's intended decision for handling the return when it arrives at the warehouse. Required at creation. May be replaced any time before release via the dedicated merchant-decision endpoint.

Responses

Request samples

Content type
application/json
{
  • "name": null,
  • "type": "customer_return",
  • "remarks": null,
  • "original_order": {
    },
  • "merchant_reference": null,
  • "items": [
    ],
  • "services": [ ],
  • "tracking_codes": [
    ],
  • "manual_close": null,
  • "force_destroy": null,
  • "merchant_decision": {
    }
}

Response samples

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