> ## 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. # Add Returning Item User Input > Adds user input for a specific returning item. This allows collecting additional information from the customer about their return. ## OpenAPI ````yaml post /draft-returns/{draft_return_id}/returning-items/{returning_item_id}/user-input/{user_input_id} openapi: 3.1.0 info: title: Draft Returns API version: v1 description: > # Overview The Draft Returns API provides a **state-aware, HATEOAS-driven interface** for building returns. This API guides clients through the return creation process using hypermedia links that describe available actions at each step. ## HATEOAS Architecture Every response includes a `links` array containing available actions you can take based on the current state of the draft return. These links are: - **Self-describing**: Each link includes a description and field metadata - **State-aware**: Only valid actions for the current state are returned - **Discoverable**: Follow the links to build the return without hardcoding workflows ### Basic Workflow 1. **Initialize** a draft return with order information 2. **Review** the response to see available actions in the `links` array 3. **Take action** by calling one of the provided link endpoints 4. **Repeat** until the return is ready to submit Each link in the `links` array provides: - `rel`: The relationship/action type - `href`: The URL to call - `method`: The HTTP method to use - `description`: Human-readable explanation of the action - `fields`: Array of required and optional fields with type information - `is_required`: Whether this action must be completed to progress ### Example Links Array ```json { "links": [ { "rel": "add-returning-item", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/returning-items", "method": "POST", "description": "Add a line item to the return", "fields": [ { "name": "order_line_item_id", "type": "int", "description": "ID of the line item to return", "is_required": true } ], "is_required": true } ] } ``` ## State Machine Draft returns progress through these states: ``` 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 Actions by State #### Created State When a draft return is in the `created` state, the following actions may be available in the `links` array: - `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 When a draft return is in the `items-finalized` state, the following actions may be available: - `set-credit-type`: Choose how to receive the refund (refund, gift card, or exchange) - `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`), no further actions are available and the `links` array will be empty. ## Workflow Examples These examples demonstrate how the `links` array evolves as a draft return progresses through states. ### Example 1: Simple Refund Return This example shows a complete workflow for returning a single item for a refund. #### Step 1: Initialize Draft Return **Request:** ```http POST /api/v1/draft-returns Content-Type: application/json { "order_name": "#1001", "secondary_input": "customer@example.com" } ``` **Response:** ```json { "draft_return": { "id": 123, "state": "created", "currency": "USD", "returning_items": [], "cart_items": [] }, "context": { "order": { "id": 42, "line_items": [ { "id": 74, "title": "Blue Shirt", "price": 2500 } ] }, "items_eligible_to_return": [ {"order_line_item_id": 74} ] }, "links": [ { "rel": "add-returning-item", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/returning-items", "method": "POST", "description": "Add a line item to the return", "fields": [ { "name": "order_line_item_id", "type": "int", "description": "ID of the line item to return", "is_required": true } ], "is_required": true } ], "errors": [] } ``` **Key observations:** - State is `created` - `context.items_eligible_to_return` shows available items - `links` array contains `add-returning-item` action marked as required #### Step 2: Add Returning Item **Request:** ```http POST /api/v1/draft-returns/123/returning-items Content-Type: application/json { "order_line_item_id": 74 } ``` **Response:** ```json { "draft_return": { "id": 123, "state": "created", "returning_items": [ { "order_line_item_id": 74, "reason": null } ] }, "context": { "return_reasons": [ {"id": 1, "name": "Too small"}, {"id": 2, "name": "Changed mind"} ] }, "links": [ { "rel": "set-returning-item-return-reason-74", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/returning-items/74/return-reason", "method": "POST", "description": "Set the return reason for this item", "fields": [ { "name": "reason_id", "type": "int", "description": "ID of the return reason", "is_required": true } ], "is_required": true }, { "rel": "finalize-items", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/finalize-items", "method": "POST", "description": "Lock in item selections and proceed", "fields": [], "is_required": false } ], "errors": [] } ``` **Key observations:** - Item was added to `returning_items` - New link appeared: `set-returning-item-return-reason` (marked required) - `context.return_reasons` provides available reasons - `finalize-items` link is available but not required #### Step 3: Set Return Reason **Request:** ```http POST /api/v1/draft-returns/123/returning-items/74/return-reason Content-Type: application/json { "reason_id": 2, "comment": "The fit wasn't right" } ``` **Response:** ```json { "draft_return": { "id": 123, "state": "created", "returning_items": [ { "order_line_item_id": 74, "reason": { "id": 2, "name": "Changed mind", "comment": "The fit wasn't right" } } ] }, "links": [ { "rel": "finalize-items", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/finalize-items", "method": "POST", "description": "Lock in item selections and proceed", "fields": [], "is_required": false } ], "errors": [] } ``` **Key observations:** - Return reason was added - No more required actions - can now finalize #### Step 4: Finalize Items **Request:** ```http POST /api/v1/draft-returns/123/finalize-items ``` **Response:** ```json { "draft_return": { "id": 123, "state": "items-finalized", "selected_return_method": null, "credit_type": null }, "context": { "return_methods": [ {"id": 1, "name": "UPS Ground", "cost": 0}, {"id": 2, "name": "USPS Priority", "cost": 0} ] }, "links": [ { "rel": "set-credit-type", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/credit-type", "method": "POST", "description": "Choose how you want your refund", "fields": [ { "name": "credit_type", "type": "enum", "description": "Type of credit", "allowed_values": ["refund", "gift", "exchange"], "is_required": true } ], "is_required": true }, { "rel": "select-return-method", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/return-method", "method": "POST", "description": "Select shipping method", "fields": [ { "name": "return_method_id", "type": "int", "description": "ID of return method", "is_required": true } ], "is_required": true } ], "errors": [] } ``` **Key observations:** - **State changed to `items-finalized`** - `links` array completely changed - different actions available - Two required actions: set credit type and select return method - `context.return_methods` provides available shipping options #### Step 5: Set Credit Type **Request:** ```http POST /api/v1/draft-returns/123/credit-type Content-Type: application/json { "credit_type": "refund" } ``` **Response:** ```json { "draft_return": { "id": 123, "state": "items-finalized", "credit_type": "refund" }, "links": [ { "rel": "select-return-method", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/return-method", "method": "POST", "description": "Select shipping method", "fields": [ { "name": "return_method_id", "type": "int", "is_required": true } ], "is_required": true } ], "errors": [] } ``` #### Step 6: Select Return Method **Request:** ```http POST /api/v1/draft-returns/123/return-method Content-Type: application/json { "return_method_id": 1 } ``` **Response:** ```json { "draft_return": { "id": 123, "state": "items-finalized", "credit_type": "refund", "selected_return_method": { "id": 1, "name": "UPS Ground", "type": "box-and-ship", "title": "UPS Ground" } }, "links": [ { "rel": "submit-draft-return", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/submit", "method": "POST", "description": "Submit the return for processing", "fields": [], "is_required": false } ], "errors": [] } ``` **Key observations:** - All required actions completed - `submit-draft-return` link now available - Ready for final submission #### Step 7: Submit Draft Return **Request:** ```http POST /api/v1/draft-returns/123/submit ``` **Response:** ```json { "draft_return": { "id": 123, "state": "submitted", "return_id": 456 }, "links": [], "errors": [] } ``` **Key observations:** - **State changed to `submitted` (terminal)** - `return_id` populated - draft converted to actual return - `links` array is empty - no further actions available ### Example 2: Exchange Return This example demonstrates returning an item and selecting an exchange product. #### Step 1-3: Initialize and Add Item (Same as Example 1, steps 1-3) #### Step 4: Set Return Type to Exchange **Request:** ```http POST /api/v1/draft-returns/123/returning-items/74/return-type Content-Type: application/json { "return_type": "exchange" } ``` **Response:** ```json { "draft_return": { "id": 123, "state": "created", "returning_items": [ { "order_line_item_id": 74, "return_type": "exchange" } ] }, "context": { "cart_products": [ { "id": 100, "title": "Red Shirt", "variants": [ {"id": 501, "title": "Small", "price": 2500} ] } ] }, "links": [ { "rel": "add-returning-item-exchange-item-74", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/returning-items/74/exchange-item", "method": "POST", "description": "Add exchange product for this item", "fields": [ { "name": "variant_id", "type": "int", "description": "Product variant to exchange for", "is_required": true } ], "is_required": true } ], "errors": [] } ``` **Key observations:** - Return type set to `exchange` - `context.cart_products` provides available exchange products - New link appeared: `add-returning-item-exchange-item` #### Step 5: Add Exchange Item **Request:** ```http POST /api/v1/draft-returns/123/returning-items/74/exchange-item Content-Type: application/json { "variant_id": 501 } ``` **Response:** ```json { "draft_return": { "id": 123, "state": "created", "returning_items": [ { "order_line_item_id": 74, "return_type": "exchange" } ], "cart_items": [ { "id": 201, "variant_id": 501, "title": "Red Shirt", "variant_title": "Small", "price": 2500 } ] }, "links": [ { "rel": "finalize-items", "href": "https://api.loopreturns.com/api/v1/draft-returns/123/finalize-items", "method": "POST", "fields": [], "is_required": false } ], "errors": [] } ``` **Key observations:** - Exchange item added to `cart_items` - Can now proceed to finalize #### Step 6-8: Finalize and Submit After finalizing, the workflow continues with: - Set credit type to `exchange` - Select return method - Submit draft return The response structure is the same as Example 1, steps 4-7. servers: - url: https://api.loopreturns.com/api/v1 security: [] paths: /draft-returns/{draft_return_id}/returning-items/{returning_item_id}/user-input/{user_input_id}: post: summary: Add Returning Item User Input description: > Adds user input for a specific returning item. This allows collecting additional information from the customer about their return. operationId: addReturningItemUserInput parameters: - $ref: '#/components/parameters/DraftReturnId' - $ref: '#/components/parameters/ReturningItemId' - $ref: '#/components/parameters/UserInputId' - $ref: '#/components/parameters/ShopId' requestBody: required: true content: application/json: schema: type: object required: - value properties: value: type: string description: The value of the user's input for the prompt. responses: '200': $ref: '#/components/responses/DraftReturnResponse' '401': $ref: '#/components/responses/UnauthorizedError' '422': $ref: '#/components/responses/ValidationError' 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 ReturningItemId: name: returning_item_id in: path description: The unique identifier of the returning item. required: true schema: type: integer UserInputId: name: user_input_id in: path description: The unique identifier of the user input answer. 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 responses: DraftReturnResponse: description: Successful response with draft return data. content: application/json: schema: type: object properties: draft_return: type: object description: The draft return object. properties: id: type: integer description: The unique identifier of the draft return. example: 12345 return_id: type: - integer - 'null' description: >- The unique identifier of the return, if the draft return has been submitted. example: 67890 state: type: string description: The current state of the draft return. enum: - created - items-finalized - submitted - cancelled - expired currency: type: string description: The three-character ISO 4217 currency code. examples: - USD - EUR language: type: string description: The language code for the draft return. example: en credit_type: type: - string - 'null' description: The type of credit for the return. enum: - refund - gift - exchange - null example: null processing_type: type: string description: How the return should be processed. enum: - regular - instant example: regular customer: type: object description: The customer information associated with the draft return. properties: email: type: string format: email description: The email address of the customer. example: someone@test.com shipping_address: type: object description: The shipping address for the return. properties: name: type: string description: The full name of the recipient. example: Jane Doe company: type: - string - 'null' description: The company name at the address. example: null address1: type: string description: The primary address line. example: 123 Main St address2: type: - string - 'null' description: The secondary address line. example: Apt 4 city: type: string description: The city name. example: Chicago state: type: string description: The state or province name. example: Illinois zip: type: string description: The postal code. example: '60622' country: type: string description: The full country name. example: United States country_code: type: string description: The two-letter country code. example: US phone: type: - string - 'null' description: The phone number. example: 555-555-5555 returning_items: type: array description: The items being returned. items: type: object properties: id: type: integer description: >- The unique identifier of this returning item within the draft return. example: 1 order_line_item_id: type: integer description: > The unique identifier created by Loop of the order line item being returned. example: 12346 return_type: type: - string - 'null' description: >- Whether this item is being returned for credit or exchange. enum: - credit - exchange - null example: credit resolution: type: - string - 'null' description: >- The final resolution for this item (computed based on return_type and merchant actions). enum: - return - keep - donate - reject - exchange - null example: return return_reason: type: - object - 'null' description: The return reason information. properties: name: type: string description: The name of the return reason. example: Item didn't fit comment: type: - string - 'null' description: Any additional comments about the return reason. example: null user_inputs: type: array description: >- Additional information requested by the merchant (e.g., questions about item condition). items: type: object properties: id: type: integer description: The unique identifier of the user input. example: 1 type: type: string description: The user input type. example: yes-no prompt: type: string description: The prompt text for the user input. example: Is the item still in its original packaging? value: type: - string - boolean - 'null' description: The value provided by the user. example: true image_uploads: type: array description: >- URLs of images uploaded by the customer for this item. items: type: string example: https://cdn.example.com/return-images/abc123.jpg cart_items: type: array description: >- The items in the cart for the return (exchange items or shop-now items). items: type: object properties: id: type: integer description: The unique identifier of the cart item. example: 201 variant_id: type: integer description: The product variant identifier. example: 501 product_id: type: - integer - 'null' description: The product identifier. example: 100 sku: type: - string - 'null' description: The SKU of the product variant. example: SHIRT-RED-S title: type: - string - 'null' description: The product title. example: Red Shirt variant_title: type: - string - 'null' description: The variant title (e.g., size, color). example: Small price: type: - integer - 'null' description: The price of this item in minor units (e.g. cents). example: 2500 image: type: - string - 'null' description: URL of the product image. example: https://cdn.example.com/products/red-shirt.jpg exchange_type: type: - string - 'null' description: The type of exchange (if this is an exchange item). enum: - storefront - pos-storefront - variant-storefront - advanced-storefront - advanced - exchange - pos-exchange - recommended - recommended-storefront - null example: exchange exchange_for_returning_item_id: type: - integer - 'null' description: >- The ID of the returning item this cart item is exchanging for. example: 1 selected_return_method: type: - object - 'null' description: > The selected return shipping method. Set via the select-return-method action. Available methods are provided in context.return_methods. properties: id: type: integer description: The unique identifier of the selected return method. name: type: string description: The name of the selected return method. type: type: string description: The type of the selected return method. enum: - box-and-ship - carrier-choice - drop-off - pick-up - in-store title: type: string description: | The display title of the selected return method. Falls back to the method name when no title is set. logo_url: type: string description: >- The logo URL of the selected return method, when available. location_url: type: string description: >- The location URL of the selected return method, when available. payment_intent: type: - object - 'null' description: The payment intent attached to the draft return, if any. properties: id: type: integer provider: type: string description: The payment provider. provider_intent_id: type: string description: The payment provider's intent identifier. return_key: type: - string - 'null' description: The unique key for the resulting return once submitted. context: type: object description: > Contextual data for building the return UI — available languages, the order's line items, return reasons, eligibility, exchange options, and return methods. Keys are omitted when their value is null. properties: languages: type: - array - 'null' description: The languages available for this shop. items: type: object properties: name: type: string abbreviation: type: string order: type: - object - 'null' description: The order information. properties: id: type: integer currency: type: string description: The three-character ISO 4217 currency code. line_items: type: array items: type: object properties: id: type: integer provider_product_id: type: integer provider_variant_id: type: integer title: type: string variant_title: type: - string - 'null' sku: type: - string - 'null' description: type: - string - 'null' price: type: - integer - 'null' description: The price in minor units. image: type: - string - 'null' parent_line_item_id: type: - integer - 'null' options: type: array items: type: object properties: name: type: string value: type: string return_reason_groups: type: - array - 'null' description: Groups of return reasons. items: type: object properties: id: type: integer return_reasons: type: array items: type: object properties: id: type: integer name: type: string parent_return_reason_id: type: - integer - 'null' parent_return_reason_name: type: - string - 'null' is_commentable: type: boolean requires_comments: type: boolean items_eligible_to_return: type: - array - 'null' description: > Line items that can be returned. Use order_line_item_id when calling the add-returning-item action; cross-reference context.order.line_items for details. items: type: object properties: order_line_item_id: type: integer return_reason_group_id: type: integer expiration: type: - string - 'null' items_not_eligible_to_return: type: - array - 'null' description: Line items that cannot be returned, with the reason why. items: type: object properties: order_line_item_id: type: integer ineligibility_code: type: string expiration: type: - string - 'null' return_reason_options: type: - array - 'null' description: >- Return-reason option groups (an array of arrays of options). items: type: array items: type: object properties: id: type: integer name: type: string is_commentable: type: boolean requires_comments: type: boolean exchange_options: type: - array - 'null' description: Products and variants available for exchange. items: type: object properties: product_options: type: - array - 'null' description: > The product's option dimensions (for example, Size or Color), used to build the variant selection UI. items: type: object properties: name: type: string description: The option name, for example "Size". values: type: array description: >- The available values for this option, for example ["S", "M", "L"]. product_variants: type: array description: >- The variants available to exchange into for this product. items: type: object properties: product_id: type: - integer - 'null' description: The unique identifier of the product. variant_id: type: integer description: The unique identifier of the variant. title: type: - string - 'null' description: The product title. variant_title: type: - string - 'null' description: >- The variant title, for example "Medium / Blue". product_type: type: - string - 'null' description: The product type. options: type: object description: >- A map of option name to the value selected for this variant. additionalProperties: type: string image: type: - string - 'null' description: The variant image URL. price: type: - integer - 'null' description: The variant price in minor units. currency: type: - string - 'null' description: The ISO currency code for the price. is_available: type: boolean description: >- Whether the variant is in stock and available for exchange. return_method_options: type: - array - 'null' description: Available return shipping methods for this draft return. items: type: object properties: id: type: integer description: The unique identifier of the return method. name: type: string description: The name of the return method. type: type: string description: The type of the return method. enum: - box-and-ship - carrier-choice - drop-off - pick-up - in-store fee: type: integer description: The fee in minor units. title: type: string description: | The display title of the return method. Falls back to the method name when no title is set. logo_url: type: string description: The logo URL of the return method, when available. location_url: type: string description: >- The location URL of the return method, when available. links: type: array description: > HATEOAS links representing available actions for the current draft return state. **How to use links:** 1. Check the `rel` field to identify the action 2. Review the `fields` array to see what data is required 3. Make an HTTP request to the `href` using the specified `method` 4. Include all fields marked with `is_required: true` **State-based availability:** - In `created` state: Links for adding items, setting customer, finalizing items - In `items-finalized` state: Links for setting credit type, selecting return method, submitting - In terminal states (`submitted`, `cancelled`, `expired`): No action links (empty array) The links array dynamically changes based on: - Current draft return state - Available context (eligible items, return reasons, return methods, etc.) - Merchant policy configuration items: type: object properties: rel: type: string description: > The relationship type/action key. This identifies the specific action this link represents. For actions on specific items, the rel may include the item ID (e.g., "set-returning-item-return-reason-74"). examples: - add-returning-item - set-address - set-customer - finalize-items - set-credit-type - submit-draft-return - cancel-draft-return href: type: string description: | The fully-qualified URL to call for this action. examples: - >- https://api.loopreturns.com/api/v1/draft-returns/123/returning-items - >- https://api.loopreturns.com/api/v1/draft-returns/123/address method: type: string description: | The HTTP method to use when calling this link. examples: - POST - DELETE description: type: string description: | Human-readable description of what this action does. example: Add a line item to the return prompt: type: string description: | Optional user-facing prompt text for this action. example: Which item would you like to return? fields: type: array description: > Field metadata describing the parameters needed for this action. Each field includes: - **name**: Parameter name (snake_case) - **type**: Data type (int, string, bool, enum, etc.) - **description**: Human-readable explanation - **is_required**: Whether this field must be provided - **allowed_values**: (Optional) Valid enum values for enum types **Using field metadata:** - Check `is_required` to determine mandatory vs optional fields - Use `type` for client-side validation - Display `description` to end users for guidance - For enum types, use `allowed_values` to populate dropdowns items: type: object properties: name: type: string description: The parameter name (snake_case). example: order_line_item_id type: type: string description: > The data type of the field. Common types: int, string, bool, enum. example: int description: type: string description: Human-readable description of the field. example: ID of the line item to return allowed_values: type: array description: > For enum type fields, this contains the list of valid values. items: type: string example: - refund - gift - exchange is_required: type: boolean description: > Whether this field is required for the action to succeed. example: true is_required: type: boolean description: > Whether this action is required to progress the draft return. If true, the draft return cannot be submitted until this action is completed. example: true errors: type: array description: > An array of error codes. In the event of a partial failure, the API will return all possible data as well as any error codes that were thrown. See [Error codes](/api-reference/error-codes#draft-returns-specific-errors) for a full list of possible errors. items: type: object properties: code: type: string description: The error code associated with the issue. enum: - draft-returns-not-enabled - validation-failed - action-validation-failed - shop-not-found - order-lookup-failed - order-not-found - error-retrieving-order - secondary-input-mismatch - returns-unavailable-for-order - order-has-been-cancelled - order-line-item-get-data-failed - draft-return-not-found - draft-return-version-mismatch - draft-return-not-actionable - items-not-finalizable - totals-calculation-failed - return-creation-failed - terminal-state - context-generation-failed - action-generation-failed - no-eligible-return-methods - invalid-return-method - product-variant-not-found - product-variant-unavailable - return-reason-not-found - currency-mismatch - unsupported-feature - internal-error message: type: string description: Optional error message. 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. ValidationError: description: Validation error occurred. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - validation-failed message: type: string example: Validation failed. securitySchemes: api_key: type: apiKey in: header name: X-Authorization ````