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.

POST /draft-returns/{draft_return_id}/submit

Submit Draft Return

cURL

curl --request POST \
  --url https://api.loopreturns.com/api/2026-07/draft-returns/{draft_return_id}/submit \
  --header 'X-Authorization: <api-key>'

200

{
  "draft_return": {
    "id": 12345,
    "return_id": 67890,
    "state": "created",
    "currency": "USD",
    "language": "en",
    "credit_type": null,
    "processing_type": "regular",
    "customer": {
      "email": "[e-mail]"
    },
    "shipping_address": {
      "name": "Jane Doe",
      "company": null,
      "address1": "123 Main St",
      "address2": "Apt 4",
      "city": "Chicago",
      "state": "Illinois",
      "zip": "60622",
      "country": "United States",
      "country_code": "US",
      "phone": "555-555-5555"
    },
    "returning_items": [
      {
        "id": 1,
        "order_line_item_id": 12346,
        "return_type": "credit",
        "resolution": "return",
        "return_reason": {
          "name": "Item didn't fit",
          "comment": null
        },
        "user_inputs": [
          {
            "id": 1,
            "type": "yes-no",
            "prompt": "Is the item still in its original packaging?",
            "value": true,
            "system_message": "Used cartridges cannot be returned."
          }
        ],
        "image_uploads": [
          "https://cdn.example.com/return-images/abc123.jpg"
        ]
      }
    ],
    "cart_items": [
      {
        "id": 201,
        "variant_id": 501,
        "product_id": 100,
        "sku": "SHIRT-RED-S",
        "title": "Red Shirt",
        "variant_title": "Small",
        "translated_title": "Chemise rouge",
        "translated_variant_title": "Petit",
        "price": 2500,
        "image": "https://cdn.example.com/products/red-shirt.jpg",
        "exchange_type": "exchange",
        "exchange_for_returning_item_id": 1
      }
    ],
    "selected_return_method": {
      "id": 123,
      "name": "<string>",
      "type": "box-and-ship",
      "title": "<string>",
      "logo_url": "<string>",
      "location_url": "<string>"
    },
    "payment_intent": {
      "id": 123,
      "provider": "<string>",
      "provider_intent_id": "<string>"
    },
    "return_key": "<string>",
    "requires_uncollectible_payment": false
  },
  "context": {
    "languages": [
      {
        "name": "<string>",
        "abbreviation": "<string>"
      }
    ],
    "order": {
      "id": 123,
      "currency": "<string>",
      "original_payment_transactions": [
        {
          "type": "<string>",
          "gateway": "<string>",
          "amount": 123,
          "currency": "<string>",
          "brand": "<string>",
          "last4": 123
        }
      ],
      "line_items": [
        {
          "id": 123,
          "provider_product_id": 123,
          "provider_variant_id": 123,
          "title": "<string>",
          "variant_title": "<string>",
          "sku": "<string>",
          "description": "<string>",
          "price": 123,
          "image": "<string>",
          "parent_line_item_id": 123,
          "options": [
            {
              "name": "<string>",
              "value": "<string>"
            }
          ]
        }
      ]
    },
    "return_reason_groups": [
      {
        "id": 123,
        "return_reasons": [
          {
            "id": 123,
            "name": "<string>",
            "parent_return_reason_id": 123,
            "parent_return_reason_name": "<string>",
            "is_commentable": true,
            "requires_comments": true
          }
        ]
      }
    ],
    "items_eligible_to_return": [
      {
        "order_line_item_id": 123,
        "return_reason_group_id": 123,
        "expiration": "<string>"
      }
    ],
    "items_not_eligible_to_return": [
      {
        "order_line_item_id": 123,
        "ineligibility_code": "<string>",
        "expiration": "<string>"
      }
    ],
    "return_reason_options": [
      [
        {
          "id": 123,
          "name": "<string>",
          "is_commentable": true,
          "requires_comments": true
        }
      ]
    ],
    "exchange_options": [
      {
        "product_options": [
          {
            "name": "<string>",
            "values": "<array>",
            "position": 123
          }
        ],
        "product_variants": [
          {
            "product_id": 123,
            "variant_id": 123,
            "title": "<string>",
            "variant_title": "<string>",
            "product_type": "<string>",
            "options": {},
            "image": "<string>",
            "price": 123,
            "currency": "<string>",
            "is_available": true,
            "translated_title": "<string>",
            "translated_variant_title": "<string>",
            "translated_options": [
              {
                "name": "<string>",
                "value": "<string>"
              }
            ]
          }
        ]
      }
    ],
    "return_method_options": [
      {
        "id": 123,
        "name": "<string>",
        "type": "box-and-ship",
        "fee": 123,
        "title": "<string>",
        "logo_url": "<string>",
        "location_url": "<string>"
      }
    ],
    "processing_type_options": {
      "required": false,
      "options": [
        {
          "type": "regular",
          "available": true,
          "unavailability_reason": "not-enabled",
          "authorization_amount": {
            "amount": 5000,
            "currency_code": "USD"
          },
          "charge_amount": {
            "amount": 5000,
            "currency_code": "USD"
          },
          "window_days": 14,
          "hold_window_days": null
        }
      ]
    }
  },
  "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",
      "prompt": "Which item would you like to return?",
      "fields": [
        {
          "name": "order_line_item_id",
          "type": "int",
          "description": "ID of the line item to return",
          "allowed_values": [
            "refund",
            "gift",
            "exchange"
          ],
          "is_required": true
        }
      ],
      "is_required": true
    }
  ],
  "errors": [
    {
      "code": "draft-returns-not-enabled",
      "message": "<string>"
    }
  ]
}

Authorizations

X-Authorization · string · header · required

Headers

X-Shop-Id · integer

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.

X-Loop-Locale · string

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.

Example:

"fr-CA"

Path Parameters

draft_return_id · integer · required

The unique identifier of the draft return.

Response

200

application/json

Successful response with draft return data.

draft_return · object

The draft return object.

Show child attributes

context · object

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.

Show child attributes

links · object[]

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

Show child attributes

errors · object[]

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 for a full list of possible errors.

Show child attributes