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
}
'import requests
url = "https://api.loopreturns.com/api/v1/draft-returns"
payload = {
"order_name": "#1001",
"secondary_input": "<string>",
"is_gift": False
}
headers = {
"X-Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Authorization': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({order_name: '#1001', secondary_input: '<string>', is_gift: false})
};
fetch('https://api.loopreturns.com/api/v1/draft-returns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.loopreturns.com/api/v1/draft-returns",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'order_name' => '#1001',
'secondary_input' => '<string>',
'is_gift' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.loopreturns.com/api/v1/draft-returns"
payload := strings.NewReader("{\n \"order_name\": \"#1001\",\n \"secondary_input\": \"<string>\",\n \"is_gift\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.loopreturns.com/api/v1/draft-returns")
.header("X-Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"order_name\": \"#1001\",\n \"secondary_input\": \"<string>\",\n \"is_gift\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.loopreturns.com/api/v1/draft-returns")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"order_name\": \"#1001\",\n \"secondary_input\": \"<string>\",\n \"is_gift\": false\n}"
response = http.request(request)
puts response.read_body{
"_links": {
"self": {
"href": "<string>"
}
},
"_templates": {},
"client_application": {},
"draft_return": {
"id": 12345,
"return_id": 67890,
"state": "created",
"currency": "USD",
"language": "en",
"credit_type": null,
"processing_type": "regular",
"customer": {
"email": "someone@test.com"
},
"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
}
],
"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",
"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>"
},
"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>"
}
],
"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
}
]
}
],
"return_method_options": [
{
"id": 123,
"name": "<string>",
"type": "box-and-ship",
"fee": 123,
"title": "<string>",
"logo_url": "<string>",
"location_url": "<string>"
}
]
},
"errors": [
{
"code": "draft-returns-not-enabled",
"message": "<string>"
}
]
}{
"errors": [
{
"code": "unauthorized",
"message": "Unauthorized."
}
]
}{
"errors": [
{
"code": "validation-failed",
"message": "Validation failed."
}
]
}Initialize Draft Return
Initialize a new draft return and receive a response.
The return created using this endpoint can be configured and modified using
the other draft return API endpoints. This endpoint should be the first
one called. The response includes the initial state of the draft return
and _links / _templates describing the next available actions.
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
}
'import requests
url = "https://api.loopreturns.com/api/v1/draft-returns"
payload = {
"order_name": "#1001",
"secondary_input": "<string>",
"is_gift": False
}
headers = {
"X-Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Authorization': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({order_name: '#1001', secondary_input: '<string>', is_gift: false})
};
fetch('https://api.loopreturns.com/api/v1/draft-returns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.loopreturns.com/api/v1/draft-returns",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'order_name' => '#1001',
'secondary_input' => '<string>',
'is_gift' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.loopreturns.com/api/v1/draft-returns"
payload := strings.NewReader("{\n \"order_name\": \"#1001\",\n \"secondary_input\": \"<string>\",\n \"is_gift\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.loopreturns.com/api/v1/draft-returns")
.header("X-Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"order_name\": \"#1001\",\n \"secondary_input\": \"<string>\",\n \"is_gift\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.loopreturns.com/api/v1/draft-returns")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"order_name\": \"#1001\",\n \"secondary_input\": \"<string>\",\n \"is_gift\": false\n}"
response = http.request(request)
puts response.read_body{
"_links": {
"self": {
"href": "<string>"
}
},
"_templates": {},
"client_application": {},
"draft_return": {
"id": 12345,
"return_id": 67890,
"state": "created",
"currency": "USD",
"language": "en",
"credit_type": null,
"processing_type": "regular",
"customer": {
"email": "someone@test.com"
},
"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
}
],
"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",
"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>"
},
"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>"
}
],
"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
}
]
}
],
"return_method_options": [
{
"id": 123,
"name": "<string>",
"type": "box-and-ship",
"fee": 123,
"title": "<string>",
"logo_url": "<string>",
"location_url": "<string>"
}
]
},
"errors": [
{
"code": "draft-returns-not-enabled",
"message": "<string>"
}
]
}{
"errors": [
{
"code": "unauthorized",
"message": "Unauthorized."
}
]
}{
"errors": [
{
"code": "validation-failed",
"message": "Validation failed."
}
]
}Authorizations
Headers
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.
Optional. Responses use Content-Type: application/prs.hal-forms+json.
application/prs.hal-forms+json Body
The order name (the merchant's order identifier, for example an order number).
"#1001"
Any secondary input included by the shopper when looking up their order (for example, ZIP/postal code or email address).
Whether or not the return will use Loop's Gift flow.
false
Response
Successful response with draft return data.
The response uses Content-Type: application/prs.hal-forms+json and includes hypermedia
controls in _links and _templates instead of the standard links array.
HAL _links object. Always includes self. Other keys are relation names
corresponding to available actions for the current draft return state.
Show child attributes
Show child attributes
_templates object. Each key is a template/action name matching a
relation in _links. Templates describe the method, fields, and constraints
for the action.
Show child attributes
Show child attributes
Client-application header specification. Describes how the client should identify itself in subsequent requests.
The draft return object.
Show child attributes
Show child attributes
Contextual data for building the return UI. Keys are omitted when their value is null.
Show child attributes
Show child attributes
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
Show child attributes