> ## 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 Draft Returns

> Returns a collection describing the draft-return actions available for
the shop.

**This endpoint requires `Accept: application/prs.hal-forms+json`**; any other Accept value
returns an `unsupported-feature` error. This is the entry point for clients
to discover available actions and initialize new draft returns.

The response includes `_templates` describing available operations (e.g. `initialize`)
and `_embedded` containing any existing draft returns for the shop.




## OpenAPI

````yaml draft-returns-hal-forms get /draft-returns
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:
    get:
      summary: List Draft Returns
      description: >
        Returns a collection describing the draft-return actions available for

        the shop.


        **This endpoint requires `Accept: application/prs.hal-forms+json`**; any
        other Accept value

        returns an `unsupported-feature` error. This is the entry point for
        clients

        to discover available actions and initialize new draft returns.


        The response includes `_templates` describing available operations (e.g.
        `initialize`)

        and `_embedded` containing any existing draft returns for the shop.
      operationId: listDraftReturnsHalForms
      parameters:
        - $ref: '#/components/parameters/ShopId'
        - $ref: '#/components/parameters/AcceptHalForms'
      responses:
        '200':
          description: OK
          content:
            application/prs.hal-forms+json:
              schema:
                type: object
                properties:
                  _links:
                    type: object
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                  _embedded:
                    type: object
                    properties:
                      draft-returns:
                        type: array
                        description: Existing draft returns for this shop, if any.
                        items:
                          type: object
                  client_application:
                    type: object
                    description: The client-application header specification.
                  _templates:
                    type: object
                    description: >
                      templates for the available actions, keyed by template
                      name.

                      Typically includes an `initialize` template for creating a
                      new draft return.
                    additionalProperties:
                      $ref: '#/components/schemas/HalFormsTemplate'
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/DraftReturnError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
        - api_key: []
components:
  parameters:
    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:
    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'
    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.
    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
  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.
    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

````