> ## 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.

# Submit Draft Return

> Submits the draft return.
This finalizes the return and initiates any necessary workflows.
Once the return has been submitted, it can be processed.

If no return policy covers the address on the draft return, the response is a `422`
with `errors[0].code` set to `returns-unavailable-for-order`. The draft return stays
open. Do not retry the submit; ask the shopper for a different address or stop the return.

If the cart still has Shop Now items while a credit item's excluded outcomes (as returned on its
line item) include Shop Now, the response is a `422` with the message "Shop Now is not available
for the items in this return. Remove the new items to continue." Remove those cart
items and submit again. In-store (point of sale) returns are unaffected.

The draft return is ready to submit when the `submit-draft-return` link (HAL-Forms: the
`submit-draft-return` template) is present. Use it as the single readiness signal rather
than working it out from other actions: Loop only offers it once every required step is
complete.




## OpenAPI

````yaml openapi/draft-returns.yaml post /draft-returns/{draft_return_id}/submit
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


    The draft return is ready to submit when the `submit-draft-return` link
    (HAL-Forms: the

    `submit-draft-return` template) is present. Use it as the single readiness
    signal rather

    than working it out from other actions: Loop only offers it once every
    required step is

    complete.


    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


    Whether an action's link is present, and its `is_required` flag (HAL-Forms:
    the template

    and its `required` flag), describe only that one action, not the draft
    return as a whole.

    The only reliable signal that the draft return is ready to submit is the
    presence of the

    `submit-draft-return` link (HAL-Forms: the `submit-draft-return` template).


    ### 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 the return type for an item. Send
    only a value from
      that item's link `allowed_values`
    - `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)

    - `set-processing-type`: Choose `regular` or `instant` processing. See
    Processing type below

    - `select-return-method`: Select the shipping method for the return

    - `add-payment-intent`: Attach a payment intent when the draft return
    requires a payment.
      Not offered when the shop has no usable Stripe connection.
    - `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.


    ## User input


    Each unanswered merchant question on a returning item has its own

    `add-returning-item-user-input` link. The link `prompt` is the question.
    After the shopper

    answers, the question is in `returning_items[].user_inputs[]` with the same
    `prompt`.


    Merchants can format a question with bold text, links, and more than one
    paragraph. Requests

    without the HAL Forms `Accept` header get `prompt` and `system_message` as
    plain text. If the

    merchant formatted the value, you get only the text before the first
    formatting change or new

    paragraph. Match on this text to find the question.


    To get the formatted HTML, send `Accept: application/prs.hal-forms+json`.
    The response then

    uses the HAL Forms format. The `unstable` version always uses the HAL Forms
    format.


    ## Processing type


    `draft_return.processing_type` is `regular` or `instant`. Every draft return
    starts as

    `regular`.


    In the `items-finalized` state, `context.processing_type_options` shows
    whether each

    processing type is available, and the amounts for Instant. To change the
    processing type,

    call the `set-processing-type` link and send only a value from its
    `allowed_values`.


    When the draft has an exchange item, Instant runs as Instant Exchange. It
    stays available

    even when the credit type is `refund`.


    ### Instant reset


    While the draft is in `items-finalized`, Loop checks again on every request
    (including

    `GET` and submit) whether Instant is still available. If it is not, Loop:


    - sets `draft_return.processing_type` to `regular`

    - removes the payment intent, so `draft_return.payment_intent` is `null`


    Before you submit, read `processing_type` and `payment_intent` in the latest
    response. If you

    still want Instant and it is available again, set it again and attach a new
    payment intent.


    `unfinalize-items` also sets `processing_type` back to `regular`.


    ## Payment


    A draft return can require a payment, for example when the shopper owes
    money after

    exchanging into a pricier item, or when `processing_type` is `instant`. Loop
    collects it

    through the shop's Stripe connection:


    - If the shop has a usable Stripe connection, the `add-payment-intent` link
    is offered and
      marked required. Call it before you submit.
    - If the shop has no usable Stripe connection, Loop cannot collect the
    payment. The
      `add-payment-intent` link is not offered, and `draft_return.requires_uncollectible_payment`
      is `true`. The draft return cannot be submitted in this state. To continue, change the
      draft so no payment is needed, for example by changing items or the return method.

    If Instant stops being available, Loop resets `processing_type` to `regular`
    and removes the

    payment intent, so `draft_return.payment_intent` comes back `null`. Check
    `processing_type`

    and `payment_intent` before you submit. If a payment is still needed, the

    `add-payment-intent` link is offered again.


    ## 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,
          "original_payment_transactions": [
            {
              "type": "sale",
              "gateway": "shopify_payments",
              "amount": 2500,
              "currency": "USD",
              "brand": "visa",
              "last4": 4242
            }
          ],
          "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/2026-07
    description: 2026-07
security: []
paths:
  /draft-returns/{draft_return_id}/submit:
    post:
      summary: Submit Draft Return
      description: >
        Submits the draft return.

        This finalizes the return and initiates any necessary workflows.

        Once the return has been submitted, it can be processed.


        If no return policy covers the address on the draft return, the response
        is a `422`

        with `errors[0].code` set to `returns-unavailable-for-order`. The draft
        return stays

        open. Do not retry the submit; ask the shopper for a different address
        or stop the return.


        If the cart still has Shop Now items while a credit item's excluded
        outcomes (as returned on its

        line item) include Shop Now, the response is a `422` with the message
        "Shop Now is not available

        for the items in this return. Remove the new items to continue." Remove
        those cart

        items and submit again. In-store (point of sale) returns are unaffected.


        The draft return is ready to submit when the `submit-draft-return` link
        (HAL-Forms: the

        `submit-draft-return` template) is present. Use it as the single
        readiness signal rather

        than working it out from other actions: Loop only offers it once every
        required step is

        complete.
      operationId: submitDraftReturn
      parameters:
        - $ref: '#/components/parameters/DraftReturnId'
        - $ref: '#/components/parameters/ShopId'
        - $ref: '#/components/parameters/LoopLocale'
      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
    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
    LoopLocale:
      name: X-Loop-Locale
      in: header
      required: false
      description: >
        The shopper's locale: a two-letter language code with an optional
        two-letter region,

        for example `fr` or `fr-CA`.


        When the value is valid and product translations are enabled for the
        shop, the response includes translated

        product text in the operation's translated fields. Otherwise those
        fields are not populated.
      schema:
        type: string
        example: fr-CA
  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. Every draft return
                      starts as `regular`.

                      Change it with the `set-processing-type` link.

                      `context.processing_type_options` shows which values are
                      available.


                      While the draft is in `items-finalized`, Loop checks on
                      every request whether

                      Instant is still available. If it is not, Loop sets
                      `processing_type` to

                      `regular` and removes the payment intent, so
                      `payment_intent` is `null`.

                      Check `processing_type` and `payment_intent` again before
                      you submit.
                    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:
                            id:
                              type: integer
                              description: The unique identifier of the return reason.
                              example: 1
                            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 merchant's question as plain text. If the
                                  merchant formatted the question,

                                  this is only the text before the first
                                  formatting change or new paragraph.

                                  See 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
                              system_message:
                                type: string
                                description: >
                                  The merchant's "Response if yes" message as
                                  plain text, in the same form as

                                  `prompt`. Only present when the merchant
                                  turned that response on.
                                example: Used cartridges cannot be returned.
                        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
                        translated_title:
                          type:
                            - string
                            - 'null'
                          description: >
                            The product title in the shopper's locale, set when
                            the item is added.

                            `null` when no locale was sent, product translations
                            are not enabled for the shop,

                            or no translation exists.
                          example: Chemise rouge
                        translated_variant_title:
                          type:
                            - string
                            - 'null'
                          description: >
                            The variant title in the shopper's locale, set when
                            the item is added.

                            `null` under the same conditions as
                            `translated_title`.
                          example: Petit
                        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.


                      Loop removes it, and this field becomes `null`, when you
                      set

                      `processing_type` to `regular` or when Loop resets Instant
                      to `regular`

                      because Instant is no longer available.
                    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.
                  requires_uncollectible_payment:
                    type: boolean
                    description: >
                      `true` when the draft return requires a payment but the
                      shop has no usable

                      Stripe connection, so Loop cannot collect it. When `true`,
                      the

                      `add-payment-intent` link is not offered and the draft
                      return cannot be

                      submitted. Change the draft so no payment is needed, for
                      example by changing

                      items or the return method.
                    example: false
              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.
                      original_payment_transactions:
                        type: array
                        description: >
                          The original payment transactions on the order,
                          excluding refunds,

                          voids, and authorizations. Useful for identifying
                          which payment

                          methods the customer used when placing the order.
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              description: The transaction type (e.g. "sale", "capture").
                            gateway:
                              type:
                                - string
                                - 'null'
                              description: The payment gateway used for the transaction.
                            amount:
                              type: integer
                              description: >-
                                The transaction amount in minor units (e.g.
                                cents).
                            currency:
                              type: string
                              description: The three-character ISO 4217 currency code.
                            brand:
                              type:
                                - string
                                - 'null'
                              description: >-
                                The card brand (e.g. "visa", "mastercard"), if
                                applicable.
                            last4:
                              type:
                                - integer
                                - 'null'
                              description: >-
                                The last four digits of the card number, if
                                applicable.
                      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"].
                              position:
                                type:
                                  - integer
                                  - 'null'
                                description: >
                                  The 1-based Shopify product option position
                                  this dimension maps to

                                  (for example, 2 when Size is option2). Clients
                                  should read variant

                                  option values by this position, not by array
                                  index, because

                                  single-value options may be omitted from this
                                  list.
                        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.
                              translated_title:
                                type:
                                  - string
                                  - 'null'
                                description: >
                                  The product title in the shopper's locale.
                                  `null` when no locale was sent,

                                  product translations are not enabled for the
                                  shop, or no translation exists.

                                  `title` always stays in the default language.
                              translated_variant_title:
                                type:
                                  - string
                                  - 'null'
                                description: >
                                  The variant title in the shopper's locale.
                                  `null` under the same conditions as

                                  `translated_title`. `variant_title` always
                                  stays in the default language.
                              translated_options:
                                type: array
                                description: >
                                  The variant's options in the shopper's locale,
                                  one entry per option in

                                  `product_options` and in the same order. Each
                                  name and value falls back to its

                                  default-language text. Empty when no option
                                  name or value is translated.
                                items:
                                  type: object
                                  properties:
                                    name:
                                      type: string
                                      description: The option name, for example "Taille".
                                    value:
                                      type: string
                                      description: >-
                                        The value selected for this variant, for
                                        example "Petit".
                  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.
                  processing_type_options:
                    $ref: '#/components/schemas/ProcessingTypeOptions'
              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,
                  setting processing 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. On

                        `add-returning-item-user-input` links, this is the
                        merchant's question as plain

                        text. See User input.
                      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.
  schemas:
    ProcessingTypeOptions:
      type: object
      description: |
        Which processing types the draft return can use.

        Present only in the `items-finalized` state. Omitted in other states.
      properties:
        required:
          type: boolean
          description: >
            `true` when the return policy requires Instant. In that case the
            `regular` option has

            `available: false` with `unavailability_reason: instant-required`.
          example: false
        options:
          type: array
          description: One entry for `regular` and one for `instant`.
          items:
            $ref: '#/components/schemas/ProcessingTypeOption'
    ProcessingTypeOption:
      type: object
      properties:
        type:
          type: string
          description: The processing type this entry describes.
          enum:
            - regular
            - instant
        available:
          type: boolean
          description: >
            Whether you can set this processing type now. Send only an available
            type to

            `set-processing-type`.


            When the draft has an exchange item, Instant runs as Instant
            Exchange and stays

            available even when the credit type is `refund`.
        unavailability_reason:
          type:
            - string
            - 'null'
          description: >
            Why this type is not available. `null` when `available` is `true`.


            - `not-enabled`: Instant is not turned on for this shop or return
            policy, or the shop
              cannot take the payment.
            - `not-applicable`: Instant does not apply to this draft, for
            example an in-store
              return, a return where every item is kept, or a return with nothing to charge.
            - `excluded`: An item in the draft is excluded from Instant.

            - `instant-required`: Only on `regular`. The return policy requires
            Instant.
          enum:
            - not-enabled
            - not-applicable
            - excluded
            - instant-required
            - null
        authorization_amount:
          description: >
            Only on an available `instant` option. The amount Loop holds
            (authorizes) on the

            shopper's payment method for Instant. `null` otherwise.
          oneOf:
            - $ref: '#/components/schemas/ProcessingTypeMoney'
            - type: 'null'
        charge_amount:
          description: >
            Only on an available `instant` option. The amount Loop charges for
            Instant. `null`

            otherwise.
          oneOf:
            - $ref: '#/components/schemas/ProcessingTypeMoney'
            - type: 'null'
        window_days:
          type:
            - integer
            - 'null'
          description: >
            Only on an available `instant` option. The Instant window, in days,
            from the return

            policy. `null` otherwise.
          example: 14
        hold_window_days:
          type:
            - integer
            - 'null'
          description: >
            Only on an available `instant` option when Instant applies to a
            refund rather than an

            exchange. The hold window, in days, from the return policy. `null`
            otherwise.
          example: null
    ProcessingTypeMoney:
      type: object
      properties:
        amount:
          type: integer
          description: The amount in minor units (e.g. cents).
          example: 5000
        currency_code:
          type: string
          description: The three-character ISO 4217 currency code.
          example: USD
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-Authorization

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.