> ## 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 Cart Item > Adds an item to the draft return's cart. ## OpenAPI ````yaml draft-returns-hal-forms post /draft-returns/{draft_return_id}/cart/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}/cart/items: post: summary: Add Cart Item description: | Adds an item to the draft return's cart. operationId: addCartItemHalForms parameters: - $ref: '#/components/parameters/DraftReturnId' - $ref: '#/components/parameters/ShopId' - $ref: '#/components/parameters/AcceptHalForms' requestBody: required: true content: application/json: schema: type: object required: - variant_id properties: variant_id: type: integer description: The unique identifier of the product variant to add. quantity: type: integer description: The quantity of the item to add. responses: '200': $ref: '#/components/responses/HalFormsDraftReturnResponse' '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 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 responses: HalFormsDraftReturnResponse: description: > Successful response with draft return data. The response uses `Content-Type: application/prs.hal-forms+json` and includes hypermedia controls in `_links` and `_templates` instead of the standard `links` array. content: application/prs.hal-forms+json: schema: type: object properties: _links: $ref: '#/components/schemas/HalFormsLinks' _templates: $ref: '#/components/schemas/HalFormsTemplates' client_application: type: object description: > Client-application header specification. Describes how the client should identify itself in subsequent requests. draft_return: $ref: '#/components/schemas/DraftReturn' context: $ref: '#/components/schemas/DraftReturnContext' 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: $ref: '#/components/schemas/DraftReturnError' 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. 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' HalFormsTemplates: type: object description: > `_templates` object. Each key is a template/action name matching a relation in `_links`. Templates describe the method, fields, and constraints for the action. additionalProperties: $ref: '#/components/schemas/HalFormsTemplate' DraftReturn: 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 example: Jane Doe company: type: - string - 'null' example: null address1: type: string example: 123 Main St address2: type: - string - 'null' example: Apt 4 city: type: string example: Chicago state: type: string example: Illinois zip: type: string example: '60622' country: type: string example: United States country_code: type: string example: US phone: type: - string - 'null' 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' enum: - credit - exchange - null example: credit resolution: type: - string - 'null' enum: - return - keep - donate - reject - exchange - null example: return return_reason: type: - object - 'null' properties: name: type: string example: Item didn't fit comment: type: - string - 'null' example: null user_inputs: type: array items: type: object properties: id: type: integer example: 1 type: type: string example: yes-no prompt: type: string example: Is the item still in its original packaging? value: type: - string - boolean - 'null' example: true image_uploads: type: array items: type: string example: https://cdn.example.com/return-images/abc123.jpg cart_items: type: array description: The items in the cart (exchange items or shop-now items). items: type: object properties: id: type: integer example: 201 variant_id: type: integer example: 501 product_id: type: - integer - 'null' example: 100 sku: type: - string - 'null' example: SHIRT-RED-S title: type: - string - 'null' example: Red Shirt variant_title: type: - string - 'null' example: Small price: type: - integer - 'null' description: The price in minor units (e.g. cents). example: 2500 image: type: - string - 'null' example: https://cdn.example.com/products/red-shirt.jpg exchange_type: type: - string - 'null' 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' example: 1 selected_return_method: type: - object - 'null' description: The selected return shipping method. properties: id: type: integer name: type: string type: type: string enum: - box-and-ship - carrier-choice - drop-off - pick-up - in-store title: type: string logo_url: type: string location_url: type: string payment_intent: type: - object - 'null' description: The payment intent attached to the draft return, if any. properties: id: type: integer provider: type: string provider_intent_id: type: string return_key: type: - string - 'null' description: The unique key for the resulting return once submitted. DraftReturnContext: type: object description: > Contextual data for building the return UI. Keys are omitted when their value is null. properties: languages: type: - array - 'null' items: type: object properties: name: type: string abbreviation: type: string order: type: - object - 'null' properties: id: type: integer currency: type: string original_payment_transactions: type: array items: type: object properties: type: type: string gateway: type: - string - 'null' amount: type: integer currency: type: string brand: type: - string - 'null' last4: type: - integer - 'null' 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' 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' 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' 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' items: type: object properties: order_line_item_id: type: integer ineligibility_code: type: string expiration: type: - string - 'null' return_reason_options: type: - array - 'null' 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' items: type: object properties: product_options: type: - array - 'null' items: type: object properties: name: type: string values: type: array product_variants: type: array items: type: object properties: product_id: type: - integer - 'null' variant_id: type: integer title: type: - string - 'null' variant_title: type: - string - 'null' product_type: type: - string - 'null' options: type: object additionalProperties: type: string image: type: - string - 'null' price: type: - integer - 'null' currency: type: - string - 'null' is_available: type: boolean return_method_options: type: - array - 'null' items: type: object properties: id: type: integer name: type: string type: type: string enum: - box-and-ship - carrier-choice - drop-off - pick-up - in-store fee: type: integer title: type: string logo_url: type: string location_url: type: string DraftReturnError: type: object properties: code: type: string description: The error code. 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. HalLink: type: object properties: href: type: string description: The fully-qualified URL for this link relation. required: - href HalFormsTemplate: type: object properties: method: type: string description: The HTTP method for this action (POST, DELETE, etc.). title: type: string description: Human-readable title/description of the action. contentType: type: string description: The content type of the request body. default: application/json properties: type: array description: Property descriptors for the action's fields. items: $ref: '#/components/schemas/HalFormsTemplateProperty' HalFormsTemplateProperty: type: object properties: name: type: string description: The property name (snake_case). type: type: string description: > The property type. Common types: `number`, `text`, `boolean`, `hidden`. required: type: boolean description: Whether this property is required. prompt: type: string description: Human-readable prompt/description of the property. options: type: object description: > For enum-like fields, an object with `inline` containing the list of valid values. properties: inline: type: array items: type: string securitySchemes: api_key: type: apiKey in: header name: X-Authorization ````