openapi: 3.1.0 info: title: Order Return Management Service version: 2026-08-17.2764666158 description: API for managing customer and agent order returns. servers: - url: https://api-1.test.logitrail.com description: Test / Development Server - url: https://api-1.logitrail.com description: Production Server paths: /v1/order-returns: post: summary: Create New Order Return description: 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. operationId: CreateOrderReturn security: - idp: - order_returns: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_return: type: object properties: name: default: null description: Name for the order return. anyOf: - type: string - type: "null" type: default: customer_return type: string enum: - agent_return - customer_return description: 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. example: customer_return remarks: default: null anyOf: - type: string - type: "null" original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: default: null description: The merchant's own reference associated to this return. anyOf: - type: string - type: "null" items: type: array items: type: object properties: id: anyOf: - type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. - type: "null" description: The technical Logitrail ID of this return line item. Null for legacy items written before per-item identifiers existed (no stable id to reference). product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. required: - id quantity: type: integer minimum: 0 maximum: 9007199254740991 description: The quantity of the item being returned. example: 2 original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return item. required: - id - type: "null" description: Reference to Logitrail's original order associated with this return item. If omitted, using the order return's original_order. services: default: [] description: Array of service references associated with this return item. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code merchant_decision: default: null description: This line's disposition, set by the merchant alongside the whole-return decision. Read-only input for downstream processing once authored. anyOf: - type: object properties: code: type: string enum: - to_shelf - resend - destroy description: Per-line disposition (RFC.0026 two-level decision). `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product. required: - id - type: "null" description: Replacement product this line should be restocked under instead of the original. Only meaningful alongside per-line `to_shelf`. required: - code - type: "null" required: - product - quantity description: 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). services: default: [] description: Array of service references associated with this return. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code tracking_codes: default: null description: "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." example: - JJFI123456789 anyOf: - type: array items: type: string minLength: 1 - type: "null" manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" merchant_decision: type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: Decision code indicating how the merchant wants the return handled when it arrives at the warehouse. required: - code description: 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. required: - merchant_decision required: - order_return responses: "201": description: New OrderReturn created successfully. content: application/json: schema: type: object properties: order_return: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. reference: default: null example: R1042X7K description: Logitrail's human-readable reference for this return (e.g. "R1042X7K"), analogous to an order's our_id. Assigned automatically; null only for the brief window before it has been generated. anyOf: - type: string - type: "null" name: default: null description: Name for the order return. anyOf: - type: string - type: "null" type: default: customer_return type: string enum: - agent_return - customer_return description: 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. example: customer_return status: default: pending type: string enum: - pending - accepted - resend_pending - restocking_pending - processing - processed - deleted - preinfo_received - pending_merchant_decision description: The current status of the return. example: pending remarks: default: null anyOf: - type: string - type: "null" original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: default: null description: The merchant's own reference associated to this return. anyOf: - type: string - type: "null" 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: The date and time when the return was created. updated_at: default: null description: The date and time when the return was last updated. 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" items: type: array items: type: object properties: id: anyOf: - type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. - type: "null" description: The technical Logitrail ID of this return line item. Null for legacy items written before per-item identifiers existed (no stable id to reference). product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. required: - id additionalProperties: false quantity: type: integer minimum: 0 maximum: 9007199254740991 description: The quantity of the item being returned. example: 2 original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return item. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return item. If omitted, using the order return's original_order. services: default: [] description: Array of service references associated with this return item. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false merchant_decision: default: null description: This line's disposition, set by the merchant alongside the whole-return decision. Read-only input for downstream processing once authored. anyOf: - type: object properties: code: type: string enum: - to_shelf - resend - destroy description: Per-line disposition (RFC.0026 two-level decision). `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product. required: - id additionalProperties: false - type: "null" description: Replacement product this line should be restocked under instead of the original. Only meaningful alongside per-line `to_shelf`. required: - code additionalProperties: false - type: "null" required: - product - quantity - services - merchant_decision additionalProperties: false description: 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). inbound_shipment: default: null description: Reference to Logitrail's Inbound Shipment, associated with the return. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the Inbound Shipment associated with this return. required: - id additionalProperties: false - type: "null" merchant_decision: default: null description: The merchant's decision details regarding handling of the return when it arrives to the warehouse. anyOf: - type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: Decision code indicating how the merchant wants to handle the return when it arrives at the warehouse. required: - code additionalProperties: false - type: "null" warehouse_location: default: null description: The warehouse location the return arrived at, once marked arrived. anyOf: - type: object properties: id: type: string description: The warehouse location code the return arrived at (e.g. `A-01-01`). Not a technical Logitrail ID — WarehouseLocation is keyed by a human-assigned code. required: - id additionalProperties: false - type: "null" resend_order: default: null description: Reference to the new Order created when the merchant decision is `resend_as_new`. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the new Order created by a `resend_as_new` decision. required: - id additionalProperties: false - type: "null" services: default: [] description: Array of service references associated with this return. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false tracking_codes: default: null description: "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." example: - JJFI123456789 anyOf: - type: array items: type: string minLength: 1 - type: "null" manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" origin: default: null description: "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." example: merchant anyOf: - type: string enum: - merchant - logitrail - system - type: "null" required: - id - reference - name - type - status - remarks - merchant_reference - created_at - updated_at - items - inbound_shipment - merchant_decision - warehouse_location - resend_order - services - tracking_codes - manual_close - force_destroy - origin additionalProperties: false required: - order_return 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 "500": description: Internal error while persisting the new return. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. get: summary: List Order Returns description: 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. operationId: ListOrderReturns security: - idp: - order_returns: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: Filter by status. Accepts a single value or a comma-separated / repeated list; results match any of the supplied statuses. example: pending,processing minItems: 1 type: array items: type: string enum: - pending - accepted - resend_pending - restocking_pending - processing - processed - deleted - preinfo_received - pending_merchant_decision description: Filter by status. Accepts a single value or a comma-separated / repeated list; results match any of the supplied statuses. - in: query name: type schema: description: Filter by return type. example: customer_return type: string enum: - agent_return - customer_return description: Filter by return type. - in: query name: q schema: description: "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." type: string minLength: 2 description: "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." - in: query name: original_order_id schema: description: Restrict results to returns linked to this original order id (Logitrail ObjectId, 24 hex chars). example: 64b8f0c2e1b2c3d4e5f67890 type: string pattern: ^[a-f0-9]{24}$ description: Restrict results to returns linked to this original order id (Logitrail ObjectId, 24 hex chars). - in: query name: tracking_code schema: description: Restrict results to the return carrying this carrier tracking code. example: JJFI123456789 type: string minLength: 1 description: Restrict results to the return carrying this carrier tracking code. - in: query name: created_at_min schema: description: 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. 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 return 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 return 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 return creation timestamp. Accepts YYYY-MM-DD (interpreted as end-of-day UTC) or a full ISO 8601 datetime. - in: query name: offset schema: default: 0 description: Pagination offset. Defaults to 0. type: integer minimum: 0 maximum: 9007199254740991 description: Pagination offset. Defaults to 0. - in: query name: limit schema: default: 100 description: Maximum number of returns to return. Defaults to 100, capped at 500. type: integer minimum: 1 maximum: 500 description: Maximum number of returns to return. Defaults to 100, capped at 500. responses: "200": description: Paginated list of order returns. content: application/json: schema: type: object properties: order_returns: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. reference: default: null example: R1042X7K description: Logitrail's human-readable reference for this return (e.g. "R1042X7K"), analogous to an order's our_id. Assigned automatically; null only for the brief window before it has been generated. anyOf: - type: string - type: "null" name: default: null description: Name for the order return. anyOf: - type: string - type: "null" type: default: customer_return type: string enum: - agent_return - customer_return description: 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. example: customer_return status: default: pending type: string enum: - pending - accepted - resend_pending - restocking_pending - processing - processed - deleted - preinfo_received - pending_merchant_decision description: The current status of the return. example: pending remarks: default: null anyOf: - type: string - type: "null" original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: default: null description: The merchant's own reference associated to this return. anyOf: - type: string - type: "null" 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: The date and time when the return was created. updated_at: default: null description: The date and time when the return was last updated. 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" inbound_shipment: default: null description: Reference to Logitrail's Inbound Shipment, associated with the return. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the Inbound Shipment associated with this return. required: - id additionalProperties: false - type: "null" merchant_decision: default: null description: The merchant's decision details regarding handling of the return when it arrives to the warehouse. anyOf: - type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: Decision code indicating how the merchant wants to handle the return when it arrives at the warehouse. required: - code additionalProperties: false - type: "null" warehouse_location: default: null description: The warehouse location the return arrived at, once marked arrived. anyOf: - type: object properties: id: type: string description: The warehouse location code the return arrived at (e.g. `A-01-01`). Not a technical Logitrail ID — WarehouseLocation is keyed by a human-assigned code. required: - id additionalProperties: false - type: "null" resend_order: default: null description: Reference to the new Order created when the merchant decision is `resend_as_new`. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the new Order created by a `resend_as_new` decision. required: - id additionalProperties: false - type: "null" tracking_codes: default: null description: "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." example: - JJFI123456789 anyOf: - type: array items: type: string minLength: 1 - type: "null" manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" origin: default: null description: "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." example: merchant anyOf: - type: string enum: - merchant - logitrail - system - type: "null" required: - id - reference - name - type - status - remarks - merchant_reference - created_at - updated_at - inbound_shipment - merchant_decision - warehouse_location - resend_order - tracking_codes - manual_close - force_destroy - origin additionalProperties: false description: Summary projection of an order return for list views. Omits the heavyweight `items` and `services` collections carried by the detail DTO. total: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of returns matching the filters before pagination. required: - order_returns - total additionalProperties: false description: Paginated list of the merchant order returns. "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/order-returns/{orderReturnId}: get: summary: Get Order Return Details description: Returns the full DTO of a single OrderReturn. operationId: GetOrderReturn security: - idp: - order_returns: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 return details retrieved successfully. content: application/json: schema: type: object properties: order_return: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. reference: default: null example: R1042X7K description: Logitrail's human-readable reference for this return (e.g. "R1042X7K"), analogous to an order's our_id. Assigned automatically; null only for the brief window before it has been generated. anyOf: - type: string - type: "null" name: default: null description: Name for the order return. anyOf: - type: string - type: "null" type: default: customer_return type: string enum: - agent_return - customer_return description: 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. example: customer_return status: default: pending type: string enum: - pending - accepted - resend_pending - restocking_pending - processing - processed - deleted - preinfo_received - pending_merchant_decision description: The current status of the return. example: pending remarks: default: null anyOf: - type: string - type: "null" original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: default: null description: The merchant's own reference associated to this return. anyOf: - type: string - type: "null" 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: The date and time when the return was created. updated_at: default: null description: The date and time when the return was last updated. 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" items: type: array items: type: object properties: id: anyOf: - type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. - type: "null" description: The technical Logitrail ID of this return line item. Null for legacy items written before per-item identifiers existed (no stable id to reference). product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. required: - id additionalProperties: false quantity: type: integer minimum: 0 maximum: 9007199254740991 description: The quantity of the item being returned. example: 2 original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return item. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return item. If omitted, using the order return's original_order. services: default: [] description: Array of service references associated with this return item. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false merchant_decision: default: null description: This line's disposition, set by the merchant alongside the whole-return decision. Read-only input for downstream processing once authored. anyOf: - type: object properties: code: type: string enum: - to_shelf - resend - destroy description: Per-line disposition (RFC.0026 two-level decision). `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product. required: - id additionalProperties: false - type: "null" description: Replacement product this line should be restocked under instead of the original. Only meaningful alongside per-line `to_shelf`. required: - code additionalProperties: false - type: "null" required: - product - quantity - services - merchant_decision additionalProperties: false description: 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). inbound_shipment: default: null description: Reference to Logitrail's Inbound Shipment, associated with the return. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the Inbound Shipment associated with this return. required: - id additionalProperties: false - type: "null" merchant_decision: default: null description: The merchant's decision details regarding handling of the return when it arrives to the warehouse. anyOf: - type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: Decision code indicating how the merchant wants to handle the return when it arrives at the warehouse. required: - code additionalProperties: false - type: "null" warehouse_location: default: null description: The warehouse location the return arrived at, once marked arrived. anyOf: - type: object properties: id: type: string description: The warehouse location code the return arrived at (e.g. `A-01-01`). Not a technical Logitrail ID — WarehouseLocation is keyed by a human-assigned code. required: - id additionalProperties: false - type: "null" resend_order: default: null description: Reference to the new Order created when the merchant decision is `resend_as_new`. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the new Order created by a `resend_as_new` decision. required: - id additionalProperties: false - type: "null" services: default: [] description: Array of service references associated with this return. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false tracking_codes: default: null description: "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." example: - JJFI123456789 anyOf: - type: array items: type: string minLength: 1 - type: "null" manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" origin: default: null description: "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." example: merchant anyOf: - type: string enum: - merchant - logitrail - system - type: "null" required: - id - reference - name - type - status - remarks - merchant_reference - created_at - updated_at - items - inbound_shipment - merchant_decision - warehouse_location - resend_order - services - tracking_codes - manual_close - force_destroy - origin additionalProperties: false required: - order_return 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 return not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. patch: summary: Update Order Return description: 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. operationId: UpdateOrderReturn security: - idp: - order_returns: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_return: type: object properties: name: anyOf: - type: string - type: "null" description: Name for the order return. type: type: string enum: - agent_return - customer_return description: 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. example: customer_return remarks: anyOf: - type: string - type: "null" description: Free-form remarks. original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: anyOf: - type: string - type: "null" description: The merchant's own reference associated to this return. items: type: array items: type: object properties: id: anyOf: - type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. - type: "null" description: The technical Logitrail ID of this return line item. Null for legacy items written before per-item identifiers existed (no stable id to reference). product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. required: - id quantity: type: integer minimum: 0 maximum: 9007199254740991 description: The quantity of the item being returned. example: 2 original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return item. required: - id - type: "null" description: Reference to Logitrail's original order associated with this return item. If omitted, using the order return's original_order. services: default: [] description: Array of service references associated with this return item. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code merchant_decision: default: null description: This line's disposition, set by the merchant alongside the whole-return decision. Read-only input for downstream processing once authored. anyOf: - type: object properties: code: type: string enum: - to_shelf - resend - destroy description: Per-line disposition (RFC.0026 two-level decision). `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product. required: - id - type: "null" description: Replacement product this line should be restocked under instead of the original. Only meaningful alongside per-line `to_shelf`. required: - code - type: "null" required: - product - quantity description: 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). services: default: [] description: Array of service references associated with this return. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code tracking_codes: anyOf: - type: array items: type: string minLength: 1 - type: "null" description: Carrier tracking codes for the return shipment, one entry per physical box (a return parcel can be multi-box). example: - JJFI123456789 manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" origin: default: null description: "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." example: merchant anyOf: - type: string enum: - merchant - logitrail - system - type: "null" description: 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. required: - order_return responses: "200": description: Order return updated successfully. content: application/json: schema: type: object properties: order_return: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. reference: default: null example: R1042X7K description: Logitrail's human-readable reference for this return (e.g. "R1042X7K"), analogous to an order's our_id. Assigned automatically; null only for the brief window before it has been generated. anyOf: - type: string - type: "null" name: default: null description: Name for the order return. anyOf: - type: string - type: "null" type: default: customer_return type: string enum: - agent_return - customer_return description: 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. example: customer_return status: default: pending type: string enum: - pending - accepted - resend_pending - restocking_pending - processing - processed - deleted - preinfo_received - pending_merchant_decision description: The current status of the return. example: pending remarks: default: null anyOf: - type: string - type: "null" original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: default: null description: The merchant's own reference associated to this return. anyOf: - type: string - type: "null" 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: The date and time when the return was created. updated_at: default: null description: The date and time when the return was last updated. 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" items: type: array items: type: object properties: id: anyOf: - type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. - type: "null" description: The technical Logitrail ID of this return line item. Null for legacy items written before per-item identifiers existed (no stable id to reference). product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. required: - id additionalProperties: false quantity: type: integer minimum: 0 maximum: 9007199254740991 description: The quantity of the item being returned. example: 2 original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return item. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return item. If omitted, using the order return's original_order. services: default: [] description: Array of service references associated with this return item. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false merchant_decision: default: null description: This line's disposition, set by the merchant alongside the whole-return decision. Read-only input for downstream processing once authored. anyOf: - type: object properties: code: type: string enum: - to_shelf - resend - destroy description: Per-line disposition (RFC.0026 two-level decision). `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product. required: - id additionalProperties: false - type: "null" description: Replacement product this line should be restocked under instead of the original. Only meaningful alongside per-line `to_shelf`. required: - code additionalProperties: false - type: "null" required: - product - quantity - services - merchant_decision additionalProperties: false description: 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). inbound_shipment: default: null description: Reference to Logitrail's Inbound Shipment, associated with the return. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the Inbound Shipment associated with this return. required: - id additionalProperties: false - type: "null" merchant_decision: default: null description: The merchant's decision details regarding handling of the return when it arrives to the warehouse. anyOf: - type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: Decision code indicating how the merchant wants to handle the return when it arrives at the warehouse. required: - code additionalProperties: false - type: "null" warehouse_location: default: null description: The warehouse location the return arrived at, once marked arrived. anyOf: - type: object properties: id: type: string description: The warehouse location code the return arrived at (e.g. `A-01-01`). Not a technical Logitrail ID — WarehouseLocation is keyed by a human-assigned code. required: - id additionalProperties: false - type: "null" resend_order: default: null description: Reference to the new Order created when the merchant decision is `resend_as_new`. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the new Order created by a `resend_as_new` decision. required: - id additionalProperties: false - type: "null" services: default: [] description: Array of service references associated with this return. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false tracking_codes: default: null description: "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." example: - JJFI123456789 anyOf: - type: array items: type: string minLength: 1 - type: "null" manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" origin: default: null description: "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." example: merchant anyOf: - type: string enum: - merchant - logitrail - system - type: "null" required: - id - reference - name - type - status - remarks - merchant_reference - created_at - updated_at - items - inbound_shipment - merchant_decision - warehouse_location - resend_order - services - tracking_codes - manual_close - force_destroy - origin additionalProperties: false required: - order_return 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 return not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. "409": description: Update rejected — the return has already started processing, or supplied `items` would silently orphan an existing per-item merchant decision. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. /v1/order-returns/{orderReturnId}/_cancel: post: summary: Cancel Order Return description: 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. operationId: CancelOrderReturn security: - idp: - order_returns: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: "200": description: Order return cancelled successfully. content: application/json: schema: type: object properties: order_return: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. reference: default: null example: R1042X7K description: Logitrail's human-readable reference for this return (e.g. "R1042X7K"), analogous to an order's our_id. Assigned automatically; null only for the brief window before it has been generated. anyOf: - type: string - type: "null" name: default: null description: Name for the order return. anyOf: - type: string - type: "null" type: default: customer_return type: string enum: - agent_return - customer_return description: 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. example: customer_return status: default: pending type: string enum: - pending - accepted - resend_pending - restocking_pending - processing - processed - deleted - preinfo_received - pending_merchant_decision description: The current status of the return. example: pending remarks: default: null anyOf: - type: string - type: "null" original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: default: null description: The merchant's own reference associated to this return. anyOf: - type: string - type: "null" 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: The date and time when the return was created. updated_at: default: null description: The date and time when the return was last updated. 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" items: type: array items: type: object properties: id: anyOf: - type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. - type: "null" description: The technical Logitrail ID of this return line item. Null for legacy items written before per-item identifiers existed (no stable id to reference). product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. required: - id additionalProperties: false quantity: type: integer minimum: 0 maximum: 9007199254740991 description: The quantity of the item being returned. example: 2 original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return item. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return item. If omitted, using the order return's original_order. services: default: [] description: Array of service references associated with this return item. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false merchant_decision: default: null description: This line's disposition, set by the merchant alongside the whole-return decision. Read-only input for downstream processing once authored. anyOf: - type: object properties: code: type: string enum: - to_shelf - resend - destroy description: Per-line disposition (RFC.0026 two-level decision). `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product. required: - id additionalProperties: false - type: "null" description: Replacement product this line should be restocked under instead of the original. Only meaningful alongside per-line `to_shelf`. required: - code additionalProperties: false - type: "null" required: - product - quantity - services - merchant_decision additionalProperties: false description: 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). inbound_shipment: default: null description: Reference to Logitrail's Inbound Shipment, associated with the return. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the Inbound Shipment associated with this return. required: - id additionalProperties: false - type: "null" merchant_decision: default: null description: The merchant's decision details regarding handling of the return when it arrives to the warehouse. anyOf: - type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: Decision code indicating how the merchant wants to handle the return when it arrives at the warehouse. required: - code additionalProperties: false - type: "null" warehouse_location: default: null description: The warehouse location the return arrived at, once marked arrived. anyOf: - type: object properties: id: type: string description: The warehouse location code the return arrived at (e.g. `A-01-01`). Not a technical Logitrail ID — WarehouseLocation is keyed by a human-assigned code. required: - id additionalProperties: false - type: "null" resend_order: default: null description: Reference to the new Order created when the merchant decision is `resend_as_new`. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the new Order created by a `resend_as_new` decision. required: - id additionalProperties: false - type: "null" services: default: [] description: Array of service references associated with this return. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false tracking_codes: default: null description: "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." example: - JJFI123456789 anyOf: - type: array items: type: string minLength: 1 - type: "null" manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" origin: default: null description: "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." example: merchant anyOf: - type: string enum: - merchant - logitrail - system - type: "null" required: - id - reference - name - type - status - remarks - merchant_reference - created_at - updated_at - items - inbound_shipment - merchant_decision - warehouse_location - resend_order - services - tracking_codes - manual_close - force_destroy - origin additionalProperties: false required: - order_return 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 return not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. "409": description: Cancellation is not possible — either the return is past the pre-arrival lifecycle or the linked inbound shipment is already being processed at the warehouse. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. /v1/order-returns/{orderReturnId}/_merchant-decision: post: summary: Set Merchant Decision On Order Return description: "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)." operationId: SetOrderReturnMerchantDecision security: - idp: - order_returns: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: merchant_decision: type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: "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." items: description: 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). type: array items: type: object properties: code: type: string enum: - to_shelf - resend - destroy description: This line's disposition. `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: description: Replacement product to restock this line under instead of the original. Only legal alongside per-line `to_shelf`. type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product to restock this line under. required: - id id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The Logitrail ID of the return line item this decision applies to. required: - code - id additionalProperties: false description: Per-line decision for a single item. Identifies the item by its ID (not product ID — a single item maps to one line, but product ID would be ambiguous across multiple lines of the same product). required: - code description: The merchant's decision on how to handle the return. required: - merchant_decision responses: "200": description: Merchant decision set successfully. content: application/json: schema: type: object properties: order_return: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. reference: default: null example: R1042X7K description: Logitrail's human-readable reference for this return (e.g. "R1042X7K"), analogous to an order's our_id. Assigned automatically; null only for the brief window before it has been generated. anyOf: - type: string - type: "null" name: default: null description: Name for the order return. anyOf: - type: string - type: "null" type: default: customer_return type: string enum: - agent_return - customer_return description: 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. example: customer_return status: default: pending type: string enum: - pending - accepted - resend_pending - restocking_pending - processing - processed - deleted - preinfo_received - pending_merchant_decision description: The current status of the return. example: pending remarks: default: null anyOf: - type: string - type: "null" original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: default: null description: The merchant's own reference associated to this return. anyOf: - type: string - type: "null" 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: The date and time when the return was created. updated_at: default: null description: The date and time when the return was last updated. 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" items: type: array items: type: object properties: id: anyOf: - type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. - type: "null" description: The technical Logitrail ID of this return line item. Null for legacy items written before per-item identifiers existed (no stable id to reference). product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. required: - id additionalProperties: false quantity: type: integer minimum: 0 maximum: 9007199254740991 description: The quantity of the item being returned. example: 2 original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return item. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return item. If omitted, using the order return's original_order. services: default: [] description: Array of service references associated with this return item. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false merchant_decision: default: null description: This line's disposition, set by the merchant alongside the whole-return decision. Read-only input for downstream processing once authored. anyOf: - type: object properties: code: type: string enum: - to_shelf - resend - destroy description: Per-line disposition (RFC.0026 two-level decision). `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product. required: - id additionalProperties: false - type: "null" description: Replacement product this line should be restocked under instead of the original. Only meaningful alongside per-line `to_shelf`. required: - code additionalProperties: false - type: "null" required: - product - quantity - services - merchant_decision additionalProperties: false description: 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). inbound_shipment: default: null description: Reference to Logitrail's Inbound Shipment, associated with the return. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the Inbound Shipment associated with this return. required: - id additionalProperties: false - type: "null" merchant_decision: default: null description: The merchant's decision details regarding handling of the return when it arrives to the warehouse. anyOf: - type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: Decision code indicating how the merchant wants to handle the return when it arrives at the warehouse. required: - code additionalProperties: false - type: "null" warehouse_location: default: null description: The warehouse location the return arrived at, once marked arrived. anyOf: - type: object properties: id: type: string description: The warehouse location code the return arrived at (e.g. `A-01-01`). Not a technical Logitrail ID — WarehouseLocation is keyed by a human-assigned code. required: - id additionalProperties: false - type: "null" resend_order: default: null description: Reference to the new Order created when the merchant decision is `resend_as_new`. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the new Order created by a `resend_as_new` decision. required: - id additionalProperties: false - type: "null" services: default: [] description: Array of service references associated with this return. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false tracking_codes: default: null description: "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." example: - JJFI123456789 anyOf: - type: array items: type: string minLength: 1 - type: "null" manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" origin: default: null description: "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." example: merchant anyOf: - type: string enum: - merchant - logitrail - system - type: "null" required: - id - reference - name - type - status - remarks - merchant_reference - created_at - updated_at - items - inbound_shipment - merchant_decision - warehouse_location - resend_order - services - tracking_codes - manual_close - force_destroy - origin additionalProperties: false required: - order_return 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 return not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. "409": description: "Decision cannot be set: either the return is past the decision lifecycle, or a decision is already set (or was set concurrently)." content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. /v1/order-returns/{orderReturnId}/items/{itemId}/merchant_decision: post: summary: Set Per-Item Merchant Decision On Order Return description: 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. operationId: SetOrderReturnItemMerchantDecision security: - idp: - order_returns: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: merchant_decision: type: object properties: code: type: string enum: - to_shelf - resend - destroy description: This line's disposition. `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: description: Replacement product to restock this line under instead of the original. Only legal alongside per-line `to_shelf`. type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product to restock this line under. required: - id required: - code description: 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. required: - merchant_decision responses: "200": description: Per-item merchant decision set successfully. content: application/json: schema: type: object properties: order_return: type: object properties: {} additionalProperties: {} description: Updated OrderReturn DTO. required: - order_return 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 return or item 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 with structured error code. "409": description: Order return has no whole-return merchant decision yet (set the whole-return decision first), or the return is no longer in `accepted` status (already released for processing). 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 with structured error code. /v1/order-returns/{orderReturnId}/extra_services: post: summary: Attach a LogitrailService to a customer return as a whole description: 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. operationId: AttachServiceToCustomerReturn security: - idp: - order_returns: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 customer return 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 return 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/order-returns/{orderReturnId}/items/{itemId}/extra_services: post: summary: Attach a LogitrailService to an order return line item description: 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. operationId: AttachServiceToOrderReturnItem security: - idp: - order_returns: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 return 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 return, 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/order-returns/{orderReturnId}/_request-label: post: summary: Request a return label for an order return description: "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." operationId: RequestReturnLabel security: - idp: - order_returns: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. - in: query name: wait_seconds schema: default: 10 description: 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. example: 10 type: integer minimum: 0 maximum: 10 description: 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. requestBody: content: application/json: schema: type: object properties: paperless: description: Request a paperless label instead of a printable PDF, when the carrier supports it. Defaults to false. example: false type: boolean responses: "200": description: Return-label generation finished within the wait window; final state (complete or failed) returned inline. content: application/json: schema: type: object properties: order_return_id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. return_label: type: object properties: status: type: string enum: - pending - processing - complete - failed description: Lifecycle status of the return-label request. `complete` means a downloadable label exists; `failed` means generation could not be completed (see the async logs). example: pending requested_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: When the label was requested. updated_at: default: null description: When the label state last changed. 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" paperless: default: false description: Whether this request asked for a paperless label. When true, `attachment` may legitimately stay null even once `status` is `complete`. type: boolean attachment: default: null description: Reference to the stored label PDF. Present once `status` is `complete`. anyOf: - type: object properties: id: type: string description: attachment-service id of the stored label PDF. url: type: string description: Download URL of the stored label PDF. required: - id - url additionalProperties: false - type: "null" error_code: default: null description: Stable machine-readable error code. Present when `status` is `failed`. example: return_label.generation_failed anyOf: - type: string - type: "null" error: default: null description: Generic human-readable failure message directing the merchant to contact Logitrail customer service. Present when `status` is `failed`. Intentionally does not include the upstream provider's error detail (DEV-2350) — see the async logs / `rl.err` for internal diagnostics. anyOf: - type: string - type: "null" required: - status - requested_at - updated_at - paperless - attachment - error_code - error additionalProperties: false required: - order_return_id - return_label additionalProperties: false "202": description: Return-label request accepted; generation is still running — poll GET .../return-label. content: application/json: schema: type: object properties: order_return_id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. return_label: type: object properties: status: type: string enum: - pending - processing - complete - failed description: Lifecycle status of the return-label request. `complete` means a downloadable label exists; `failed` means generation could not be completed (see the async logs). example: pending requested_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: When the label was requested. updated_at: default: null description: When the label state last changed. 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" paperless: default: false description: Whether this request asked for a paperless label. When true, `attachment` may legitimately stay null even once `status` is `complete`. type: boolean attachment: default: null description: Reference to the stored label PDF. Present once `status` is `complete`. anyOf: - type: object properties: id: type: string description: attachment-service id of the stored label PDF. url: type: string description: Download URL of the stored label PDF. required: - id - url additionalProperties: false - type: "null" error_code: default: null description: Stable machine-readable error code. Present when `status` is `failed`. example: return_label.generation_failed anyOf: - type: string - type: "null" error: default: null description: Generic human-readable failure message directing the merchant to contact Logitrail customer service. Present when `status` is `failed`. Intentionally does not include the upstream provider's error detail (DEV-2350) — see the async logs / `rl.err` for internal diagnostics. anyOf: - type: string - type: "null" required: - status - requested_at - updated_at - paperless - attachment - error_code - error additionalProperties: false required: - order_return_id - return_label 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 return not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. "409": description: The order return has no resolvable original order — a return label cannot be requested. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. /v1/order-returns/{orderReturnId}/return-label: get: summary: Get return-label status and download reference description: 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. operationId: GetReturnLabel security: - idp: - order_returns: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: Current return-label state. content: application/json: schema: type: object properties: return_label: type: object properties: status: type: string enum: - pending - processing - complete - failed description: Lifecycle status of the return-label request. `complete` means a downloadable label exists; `failed` means generation could not be completed (see the async logs). example: pending requested_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: When the label was requested. updated_at: default: null description: When the label state last changed. 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" paperless: default: false description: Whether this request asked for a paperless label. When true, `attachment` may legitimately stay null even once `status` is `complete`. type: boolean attachment: default: null description: Reference to the stored label PDF. Present once `status` is `complete`. anyOf: - type: object properties: id: type: string description: attachment-service id of the stored label PDF. url: type: string description: Download URL of the stored label PDF. required: - id - url additionalProperties: false - type: "null" error_code: default: null description: Stable machine-readable error code. Present when `status` is `failed`. example: return_label.generation_failed anyOf: - type: string - type: "null" error: default: null description: Generic human-readable failure message directing the merchant to contact Logitrail customer service. Present when `status` is `failed`. Intentionally does not include the upstream provider's error detail (DEV-2350) — see the async logs / `rl.err` for internal diagnostics. anyOf: - type: string - type: "null" required: - status - requested_at - updated_at - paperless - attachment - error_code - error additionalProperties: false required: - return_label 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 return not found, or no return label has been requested for it. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. /v1/order-returns/{orderReturnId}/attachments: get: summary: List files attached to an order return description: 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. operationId: GetOrderReturnAttachments security: - idp: - order_returns: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: Attachment list for the order return. content: application/json: schema: type: object properties: attachments: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Internal Attachment ID (24-hex MongoDB ObjectId). example: 5f9b1b9b9b9b9b9b9b9b9b9b purpose: type: string enum: - damage_evidence - return_document - other description: Purpose of the attachment. Closed enum — one of `damage_evidence`, `return_document`, `other`. remarks: description: Optional freeform comment stored alongside the link. type: string file_name: type: string description: Filename of the attachment. mime: type: string description: MIME type of the attachment. uploaded_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 when the attachment was uploaded to the system. download_link: description: Download link of the attachment, if available. type: object properties: url: type: string description: Short-lived download URL for the attachment file (use to fetch or display it). valid_until: 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: Validity period of the download URL, after which it stops working (~5 minutes). required: - url - valid_until additionalProperties: false required: - id - purpose - file_name - mime - uploaded_at additionalProperties: false description: Attachment list for the order return. required: - attachments 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 return not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. /v1/order-returns/{orderReturnId}/items/{itemId}/attachments: get: summary: List files attached to an order return's line item description: 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. operationId: GetOrderReturnItemAttachments security: - idp: - order_returns: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: Attachment list for the order return line item. content: application/json: schema: type: object properties: attachments: type: array items: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ description: Internal Attachment ID (24-hex MongoDB ObjectId). example: 5f9b1b9b9b9b9b9b9b9b9b9b purpose: type: string enum: - damage_evidence - return_document - other description: Purpose of the attachment. Closed enum — one of `damage_evidence`, `return_document`, `other`. remarks: description: Optional freeform comment stored alongside the link. type: string file_name: type: string description: Filename of the attachment. mime: type: string description: MIME type of the attachment. uploaded_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 when the attachment was uploaded to the system. download_link: description: Download link of the attachment, if available. type: object properties: url: type: string description: Short-lived download URL for the attachment file (use to fetch or display it). valid_until: 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: Validity period of the download URL, after which it stops working (~5 minutes). required: - url - valid_until additionalProperties: false required: - id - purpose - file_name - mime - uploaded_at additionalProperties: false description: Attachment list for the order return. required: - attachments 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 return or line item not found. content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. /v1/orders/{orderId}/_create-return: post: summary: Create an Order Return from an Order description: 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`. operationId: CreateOrderReturnFromOrder security: - idp: - order_returns: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: name: default: null description: Name for the order return. anyOf: - type: string - type: "null" type: default: customer_return type: string enum: - agent_return - customer_return description: 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. example: customer_return remarks: default: null anyOf: - type: string - type: "null" original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: default: null description: The merchant's own reference associated to this return. anyOf: - type: string - type: "null" items: type: array items: type: object properties: id: anyOf: - type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. - type: "null" description: The technical Logitrail ID of this return line item. Null for legacy items written before per-item identifiers existed (no stable id to reference). product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. required: - id quantity: type: integer minimum: 0 maximum: 9007199254740991 description: The quantity of the item being returned. example: 2 original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return item. required: - id - type: "null" description: Reference to Logitrail's original order associated with this return item. If omitted, using the order return's original_order. services: default: [] description: Array of service references associated with this return item. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code merchant_decision: default: null description: This line's disposition, set by the merchant alongside the whole-return decision. Read-only input for downstream processing once authored. anyOf: - type: object properties: code: type: string enum: - to_shelf - resend - destroy description: Per-line disposition (RFC.0026 two-level decision). `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product. required: - id - type: "null" description: Replacement product this line should be restocked under instead of the original. Only meaningful alongside per-line `to_shelf`. required: - code - type: "null" required: - product - quantity description: 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). services: default: [] description: Array of service references associated with this return. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code tracking_codes: default: null description: "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." example: - JJFI123456789 anyOf: - type: array items: type: string minLength: 1 - type: "null" manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" merchant_decision: type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: Decision code indicating how the merchant wants the return handled when it arrives at the warehouse. required: - code description: 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. required: - merchant_decision responses: "201": description: New OrderReturn created successfully. content: application/json: schema: type: object properties: order_return: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. reference: default: null example: R1042X7K description: Logitrail's human-readable reference for this return (e.g. "R1042X7K"), analogous to an order's our_id. Assigned automatically; null only for the brief window before it has been generated. anyOf: - type: string - type: "null" name: default: null description: Name for the order return. anyOf: - type: string - type: "null" type: default: customer_return type: string enum: - agent_return - customer_return description: 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. example: customer_return status: default: pending type: string enum: - pending - accepted - resend_pending - restocking_pending - processing - processed - deleted - preinfo_received - pending_merchant_decision description: The current status of the return. example: pending remarks: default: null anyOf: - type: string - type: "null" original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return. merchant_reference: default: null description: The merchant's own reference associated to this return. anyOf: - type: string - type: "null" 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: The date and time when the return was created. updated_at: default: null description: The date and time when the return was last updated. 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" items: type: array items: type: object properties: id: anyOf: - type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. - type: "null" description: The technical Logitrail ID of this return line item. Null for legacy items written before per-item identifiers existed (no stable id to reference). product: type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the order return. required: - id additionalProperties: false quantity: type: integer minimum: 0 maximum: 9007199254740991 description: The quantity of the item being returned. example: 2 original_order: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the original order associated with this return item. required: - id additionalProperties: false - type: "null" description: Reference to Logitrail's original order associated with this return item. If omitted, using the order return's original_order. services: default: [] description: Array of service references associated with this return item. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false merchant_decision: default: null description: This line's disposition, set by the merchant alongside the whole-return decision. Read-only input for downstream processing once authored. anyOf: - type: object properties: code: type: string enum: - to_shelf - resend - destroy description: Per-line disposition (RFC.0026 two-level decision). `resend` is only legal when the whole-return decision is `resend_as_new`. restock_as_product: anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the replacement product. required: - id additionalProperties: false - type: "null" description: Replacement product this line should be restocked under instead of the original. Only meaningful alongside per-line `to_shelf`. required: - code additionalProperties: false - type: "null" required: - product - quantity - services - merchant_decision additionalProperties: false description: 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). inbound_shipment: default: null description: Reference to Logitrail's Inbound Shipment, associated with the return. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the Inbound Shipment associated with this return. required: - id additionalProperties: false - type: "null" merchant_decision: default: null description: The merchant's decision details regarding handling of the return when it arrives to the warehouse. anyOf: - type: object properties: code: type: string enum: - resend_as_it_is - destroy - to_shelf - resend_as_new description: Decision code indicating how the merchant wants to handle the return when it arrives at the warehouse. required: - code additionalProperties: false - type: "null" warehouse_location: default: null description: The warehouse location the return arrived at, once marked arrived. anyOf: - type: object properties: id: type: string description: The warehouse location code the return arrived at (e.g. `A-01-01`). Not a technical Logitrail ID — WarehouseLocation is keyed by a human-assigned code. required: - id additionalProperties: false - type: "null" resend_order: default: null description: Reference to the new Order created when the merchant decision is `resend_as_new`. anyOf: - type: object properties: id: type: string pattern: ^[a-f0-9]{24}$ example: 64b8f0c2e1b2c3d4e5f67890 description: The technical Logitrail ID of the new Order created by a `resend_as_new` decision. required: - id additionalProperties: false - type: "null" services: default: [] description: Array of service references associated with this return. type: array items: type: object properties: code: type: string pattern: ^[a-z0-9-_]+$ required: - code additionalProperties: false tracking_codes: default: null description: "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." example: - JJFI123456789 anyOf: - type: array items: type: string minLength: 1 - type: "null" manual_close: default: null description: Present when this return was force-closed to `processed` by an internal admin action outside the normal lifecycle, instead of null. anyOf: - 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 - type: "null" force_destroy: default: null description: 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. anyOf: - 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 - type: "null" origin: default: null description: "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." example: merchant anyOf: - type: string enum: - merchant - logitrail - system - type: "null" required: - id - reference - name - type - status - remarks - merchant_reference - created_at - updated_at - items - inbound_shipment - merchant_decision - warehouse_location - resend_order - services - tracking_codes - manual_close - force_destroy - origin additionalProperties: false required: - order_return 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 (or does not belong to the requesting merchant). content: application/json: schema: type: object properties: message: type: string error_code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false description: Order-return error response body. components: securitySchemes: idp: type: oauth2 flows: clientCredentials: tokenUrl: https://idp.logitrail.com/realms/logitrail/protocol/openid-connect/token scopes: order_returns:read: Read order return data order_returns:manage: Manage order return data