Skip to main content

​
Overview

The Return Create API allows for a wide array of actions to be performed on returns, but one of the simplest ways to get started is to use the API to check the eligibility of items for return. This guide walks through the process of initializing a draft return and checking item eligibility.

​
Requirements

  • A Loop API key with the Draft Returns (read) and Draft Returns (write) scopes. For details on how to create or modify an API key, see Authentication.
  • The shop ID for the merchant’s shop.
  • The Shopify order name of the order for which you want to check the eligibility.

​
1. Initialize a Draft Return

First, initialize a draft return using the order information. This is done using the Initialize Draft Return endpoint. 
curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '{
  "shop_id": 23141001,
  "order_name": "#1001",
  "secondary_input": "90210",
  "is_gift": false
}'
The response will be the initial state of the draft return, including:
  • Lists of eligible and ineligible items
  • Available return reasons
  • Links to next possible actions
  • Any error codes thrown
See Get Draft Return for a complete example draft return response.

​
2. Check Item Eligibility

In the response from initializing the draft return, you’ll find two important arrays:
  1. items_eligible_to_return: Contains items that can be returned
  2. items_not_eligible_to_return: Contains items that can’t be returned
{
    "context": {
        "items_eligible_to_return": [
            {
                "order_line_item_id": 291523857
            }
        ],
        "items_not_eligible_to_return": [
            {
                "order_line_item_id": 12345,
                "ineligibility_code": "final-sale"
            }
        ]
    }
}
Eligibility is determined based on the merchant’s configuration, including:
  • Return policy rules
  • Time since purchase
  • Item-specific restrictions
  • Order status
The eligibility check happens automatically when initializing the draft return and continuously throughout the draft return process.

​
3. Get Detailed Return Status

At any point, you can check the current state of the draft return using the Get draft return endpoint.
Get draft return
curl --request GET \
  --url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id} \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '{
    "shop_id": 23141001
}'
This will return the complete state of the draft return, including:
  • Current eligible/ineligible items
  • Customer information
  • Return methods available
  • Any errors or issues

​
4. Handle the Results

Based on the eligibility results, you can:
  1. If there are eligible items for return:
    • Proceed with adding items to the return using the Add Returning Item endpoint.
    • Set return reasons and types for each item.
    • Continue with the return process.
  2. If no items are eligible:
    • Cancel the draft return using the Cancel Draft Return endpoint.
    • Inform the customer that no items are eligible for return.

​
Flow Summary

  1. Initialize draft return
  2. Check eligibility in response
  3. If items are eligible:
    • Add items to return
    • Set return reasons
    • Select return method
    • Submit return
  4. If no items are eligible:
    • Cancel draft return
    • Inform customer