> ## Documentation Index > Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt > Use this file to discover all available pages before exploring further. # List Order Line Items > Returns the order's line items in the context of the draft return, including return and warranty eligibility, available return reasons, variant details, and advanced-exchange options. Prices are integers in minor units (e.g. cents). ## OpenAPI ````yaml draft-returns-hal-forms get /draft-returns/{draft_return_id}/order/items openapi: 3.1.0 info: title: Draft Returns API version: v1 description: > # Overview The Draft Returns API lets you build a complete return-creation flow by managing draft returns through a state machine. Endpoints allow you to initialize a draft, add or remove items, set customer and address details, finalize selections, and submit the completed return. This document describes the unreleased API version. Test via `/api/unstable/draft-returns/...`. ## Response architecture Successful responses include `draft_return`, `context`, `errors`, plus hypermedia controls. ### `_links` An object keyed by relation name. Each value includes `href` and optional metadata: ```json { "_links": { "self": { "href": "https://api.loopreturns.com/api/unstable/draft-returns/123" }, "add-returning-item": { "href": "https://api.loopreturns.com/api/unstable/draft-returns/123/returning-items" }, "finalize-items": { "href": "https://api.loopreturns.com/api/unstable/draft-returns/123/finalize-items" } } } ``` ### `_templates` Each available action is described by a template in the `_templates` object: ```json { "_templates": { "add-returning-item": { "method": "POST", "title": "Add a line item to the return", "contentType": "application/json", "properties": [ { "name": "order_line_item_id", "type": "number", "required": true, "prompt": "ID of the line item to return" } ] }, "finalize-items": { "method": "POST", "title": "Lock in item selections and proceed", "contentType": "application/json", "properties": [] } } } ``` Each template may include: - `method`: The HTTP method (`POST`, `DELETE`, etc.) - `title`: Human-readable description of the action - `contentType`: The request content type (typically `application/json`) - `properties`: Array of field descriptors with `name`, `type`, `required`, `prompt`, and optionally `options` (for enum-like fields) ### `client_application` Responses include a `client_application` object describing how the client should identify itself on subsequent requests. ### Content type | Header | Value | |---|---| | `Content-Type` (response) | `application/prs.hal-forms+json` | | `Content-Type` (request body) | `application/json` | ## State Machine ``` created → finalize-items → items-finalized → submit → submitted ↓ ↓ ↓← ← unfinalize-items ← ← ← ← ↓ ↓ ↓ └→ cancel → cancelled expired ``` ### States - **created**: Initial state where items are added and customer information is set - **items-finalized**: Items are locked in; credit type and return method can be selected - **submitted**: Terminal state — draft has been converted to an actual return - **cancelled**: Terminal state — draft was explicitly cancelled - **expired**: Terminal state — draft timed out due to inactivity ### Available Templates by State #### Created State `_templates` may include: - `add-returning-item`: Add an item from the order to the return - `remove-returning-item`: Remove an item from the return - `set-returning-item-return-reason`: Set why an item is being returned - `set-returning-item-return-type`: Set whether the item is for credit or exchange - `add-returning-item-exchange-item`: Add an exchange product for a returning item - `add-returning-item-user-input`: Provide additional information requested by merchant - `remove-cart-item`: Remove an exchange or shop-now item - `set-customer`: Set customer email and name - `set-address`: Set return shipping address - `finalize-items`: Lock in item selections and proceed to return method selection - `cancel-draft-return`: Cancel this draft return #### Items-Finalized State `_templates` may include: - `set-credit-type`: Choose how to receive the refund - `select-return-method`: Select the shipping method for the return - `submit-draft-return`: Submit the draft and convert it to an actual return - `unfinalize-items`: Go back to add/remove items - `cancel-draft-return`: Cancel this draft return #### Terminal States When a draft return reaches a terminal state (`submitted`, `cancelled`, `expired`), `_templates` and `_links` will be empty objects. servers: - url: https://api.loopreturns.com/api/v1 security: [] paths: /draft-returns/{draft_return_id}/order/items: get: summary: List Order Line Items description: > Returns the order's line items in the context of the draft return, including return and warranty eligibility, available return reasons, variant details, and advanced-exchange options. Prices are integers in minor units (e.g. cents). operationId: getDraftReturnOrderItemsHalForms parameters: - $ref: '#/components/parameters/DraftReturnId' - $ref: '#/components/parameters/ShopId' - $ref: '#/components/parameters/AcceptHalForms' - name: page in: query description: The page number to return (default 1). schema: type: integer minimum: 1 default: 1 - name: limit in: query description: >- Number of order line items per page. Must be between 1 and 250 (inclusive). Defaults to 10. schema: type: integer minimum: 1 maximum: 250 default: 10 responses: '200': description: OK content: application/prs.hal-forms+json: schema: type: object properties: _links: $ref: '#/components/schemas/HalFormsLinks' _embedded: type: object properties: items: type: array items: type: object properties: id: type: integer description: type: - string - 'null' image: type: - string - 'null' parent_line_item_id: type: - integer - 'null' price: type: - integer - 'null' discount: type: integer discounted_price: type: - integer - 'null' compare_at_price: type: - integer - 'null' price_original: type: - integer - 'null' current_variant_price: type: - integer - 'null' outcome: type: string return_reasons: type: array items: type: object required: - id - name properties: id: type: integer name: type: string parent_return_reason_id: type: - integer - 'null' parent_return_reason_name: type: - string - 'null' eligibility: type: object properties: return: type: object properties: status: type: boolean reason: type: string expiration: type: - string - 'null' warranty: type: object properties: status: type: boolean reason: type: string expiration: type: - string - 'null' title: type: string provider_product_id: type: integer variant: type: object properties: id: type: integer title: type: - string - 'null' options: type: array items: type: object properties: name: type: string value: type: string advanced_exchange: type: - object - 'null' properties: id: type: integer title: type: string title_visible: type: boolean options: type: array items: type: object capabilities: type: array items: type: string '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Not Found security: - api_key: [] components: parameters: DraftReturnId: name: draft_return_id in: path description: The unique identifier of the draft return. required: true schema: type: integer ShopId: name: X-Shop-Id in: header description: > The unique identifier of the shop associated with the draft return. This header is not required, as the merchant's shop is identified by the API key present in the request. schema: type: integer AcceptHalForms: name: Accept in: header required: false description: | Optional. Responses use `Content-Type: application/prs.hal-forms+json`. schema: type: string enum: - application/prs.hal-forms+json schemas: HalFormsLinks: type: object description: > HAL `_links` object. Always includes `self`. Other keys are relation names corresponding to available actions for the current draft return state. properties: self: $ref: '#/components/schemas/HalLink' additionalProperties: $ref: '#/components/schemas/HalLink' HalLink: type: object properties: href: type: string description: The fully-qualified URL for this link relation. required: - href responses: UnauthorizedError: description: API key is missing or invalid. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - unauthorized message: type: string example: Unauthorized. securitySchemes: api_key: type: apiKey in: header name: X-Authorization ````