Skip to main content
POST
/
draft-returns
Initialize Draft Return
curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '
{
  "order_name": "#1001",
  "secondary_input": "<string>",
  "is_gift": false
}
'
{
  "draft_return": {
    "id": 12345,
    "return_id": 67890,
    "state": "created",
    "currency": "USD",
    "language": "en",
    "credit_type": null,
    "store_credit_type": "gift-card",
    "processing_type": "regular",
    "return_policy": {
      "id": 1,
      "name": "Standard 30-day return",
      "return_window_days": 30
    },
    "totals": {
      "return_total": {
        "amount": 5000,
        "currency": "USD"
      },
      "new_item_total": {
        "amount": 3000,
        "currency": "USD"
      },
      "total_bonus_offered": {
        "amount": 500,
        "currency": "USD"
      },
      "bonus_used": {
        "amount": 500,
        "currency": "USD"
      },
      "fees": {
        "applied": {
          "amount": 300,
          "currency": "USD"
        },
        "refund": {
          "amount": 100,
          "currency": "USD"
        },
        "credit": {
          "amount": 100,
          "currency": "USD"
        },
        "exchange": {
          "amount": 100,
          "currency": "USD"
        }
      },
      "amount_due": {
        "amount": 0,
        "currency": "USD"
      },
      "credit": {
        "remaining_credit": {
          "amount": 2000,
          "currency": "USD"
        },
        "refund_credit": {
          "amount": 2000,
          "currency": "USD"
        },
        "store_credit": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "net": {
        "amount": 2000,
        "currency": "USD"
      }
    },
    "customer": {
      "email": "[email protected]"
    },
    "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",
        "reason": {
          "id": 2,
          "name": "Item didn't fit",
          "comment": null
        },
        "user_input": [
          {
            "id": 1,
            "prompt": "Is the item still in its original packaging?",
            "value": true
          }
        ],
        "image_uploads": [
          "https://cdn.example.com/return-images/abc123.jpg"
        ],
        "has_exchange_item": false
      }
    ],
    "cart_items": [
      {
        "id": 201,
        "variant_id": 501,
        "product_id": 100,
        "sku": "SHIRT-RED-S",
        "title": "Red Shirt",
        "variant_title": "Small",
        "product_type": "Apparel",
        "price": {
          "amount": 2500,
          "currency": "USD"
        },
        "price_currency_code": "USD",
        "image": "https://cdn.example.com/products/red-shirt.jpg",
        "exchange_type": "exchange",
        "exchange_for_returning_item_id": 1
      }
    ],
    "selected_return_method": "UPS Ground"
  },
  "context": {
    "order": {
      "id": 42,
      "currency": "USD",
      "line_items": [
        {
          "id": 74,
          "provider_product_id": 7804939829359,
          "provider_variant_id": 43045586894959,
          "title": "Example Product",
          "variant_title": "Example Variant",
          "price": 2250,
          "image": "https://example.com/example.jpg"
        }
      ]
    },
    "items_eligible_to_return": [
      {
        "order_line_item_id": 74
      }
    ],
    "items_not_eligible_to_return": [
      {
        "order_line_item_id": 12347,
        "ineligibility_code": "not_eligible_for_return"
      }
    ],
    "return_reasons": [
      {
        "id": 1,
        "name": "Too small",
        "requires_comment": false,
        "child_reasons": [
          {
            "id": 10,
            "name": "Size too small"
          }
        ]
      }
    ],
    "return_methods": [
      {
        "id": 1,
        "name": "UPS Ground",
        "type": "label",
        "cost": 0,
        "carrier": "UPS"
      }
    ],
    "available_credit_types": [
      "refund"
    ],
    "cart_products": [
      {
        "id": 100,
        "title": "Red Shirt",
        "product_type": "Apparel",
        "image": "https://cdn.example.com/products/red-shirt.jpg",
        "variants": [
          {
            "id": 501,
            "title": "Small",
            "sku": "SHIRT-RED-S",
            "price": 2500,
            "available": true
          }
        ]
      }
    ]
  },
  "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": "<string>",
      "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.

Body

application/json
​
order_name
string
required

The Shopify order name.

Examples:

"#1001"

​
secondary_input
string
required

Any secondary input included by the shopper when looking up their order (for example, ZIP/postal code or email address).

​
is_gift
boolean

Whether or not the return will use Loop's Gift flow. For details, see Gift Returns.

Examples:

false

Response

Successful response with draft return data.

​
draft_return
object

The draft return object.

​
context
object

Contextual information about the draft return. The context object provides data needed for actions (e.g., eligible items, return reasons, shipping methods). Context fields are dynamically populated based on the current state and available actions.

​
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, 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
​
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.