APIs
- GETGet Draft Return
- POSTInitialize Draft Return
- POSTCancel Draft Return
- POSTSet Customer
- POSTSet Address
- POSTAdd Returning Item
- DELRemove Returning Item
- POSTSet Returning Item Return Reason
- POSTAdd Returning Item User Input
- POSTSet Returning Item Return Type
- POSTAdd Returning Item Exchange Item
- POSTAdd Cart Item
- DELRemove Cart Item
- POSTSet Credit Type
- POSTFinalize Items
- POSTUnfinalize Items
- POSTSelect Return Method
- POSTSubmit Draft Return
- GET
curl --request DELETE \
--url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/returning-items/{returning_item_id} \
--header 'X-Authorization: <api-key>'{
"draft_return": {
"id": 12345,
"return_id": 67890,
"state": "created",
"currency": "<string>",
"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": "<string>",
"href": "<string>",
"method": "<string>",
"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>"
}
]
}Remove Returning Item
Removes a specific item from the draft return’s ReturningItems.
curl --request DELETE \
--url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/returning-items/{returning_item_id} \
--header 'X-Authorization: <api-key>'{
"draft_return": {
"id": 12345,
"return_id": 67890,
"state": "created",
"currency": "<string>",
"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": "<string>",
"href": "<string>",
"method": "<string>",
"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
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.
Path Parameters
The unique identifier of the draft return.
The unique identifier of the returning item.
Response
Successful response with draft return data.
The draft return object.
Show child attributes
Show child attributes
The unique identifier of the draft return.
12345
The unique identifier of the return, if the draft return has been submitted.
67890
The current state of the draft return.
created, returning-items-finalized, submitted, cancelled, expired The three-character ISO 4217 currency code.
The language code for the draft return.
"en"
The type of credit for the return.
refund, gift, exchange, null
The type of store credit to issue when credit_type is 'gift'.
gift-card, reshop "gift-card"
How the return should be processed.
regular, instant "regular"
The return policy applied to this draft return.
Show child attributes
Show child attributes
The unique identifier of the return policy.
1
The name of the return policy.
"Standard 30-day return"
The number of days allowed for returns under this policy.
30
Calculated totals for the return, including credits, fees, and amounts due.
Show child attributes
Show child attributes
Fees associated with the return.
Show child attributes
Show child attributes
Credit amounts for the return.
Show child attributes
Show child attributes
The customer information associated with the draft return.
Show child attributes
Show child attributes
The email address of the customer.
The shipping address for the return.
Show child attributes
Show child attributes
The full name of the recipient.
"Jane Doe"
The company name at the address.
null
The primary address line.
"123 Main St"
The secondary address line.
"Apt 4"
The city name.
"Chicago"
The state or province name.
"Illinois"
The postal code.
"60622"
The full country name.
"United States"
The two-letter country code.
"US"
The phone number.
"555-555-5555"
The items being returned.
Show child attributes
Show child attributes
The unique identifier of this returning item within the draft return.
1
The unique identifier created by Loop of the order line item being returned.
12346
Whether this item is being returned for credit or exchange.
credit, exchange, "credit"
The final resolution for this item (computed based on return_type and merchant actions).
return, keep, donate, reject, exchange, "return"
The return reason information.
Show child attributes
Show child attributes
The unique identifier of the return reason.
2
The name of the return reason.
"Item didn't fit"
Any additional comments about the return reason.
null
Additional information requested by the merchant (e.g., questions about item condition).
Show child attributes
Show child attributes
The unique identifier of the user input.
1
The prompt text for the user input.
"Is the item still in its original packaging?"
The value provided by the user.
true
URLs of images uploaded by the customer for this item.
Whether an exchange item has been added for this returning item.
false
The items in the cart for the return (exchange items or shop-now items).
Show child attributes
Show child attributes
The unique identifier of the cart item.
201
The product variant identifier.
501
The product identifier.
100
The SKU of the product variant.
"SHIRT-RED-S"
The product title.
"Red Shirt"
The variant title (e.g., size, color).
"Small"
The product type/category.
"Apparel"
The currency code for the price.
"USD"
URL of the product image.
"https://cdn.example.com/products/red-shirt.jpg"
The type of exchange (if this is an exchange item).
storefront, pos-storefront, variant-storefront, advanced-storefront, advanced, exchange, pos-exchange, "exchange"
The ID of the returning item this cart item is exchanging for.
1
The name of the selected return shipping method. Set via the select-return-method action. Available methods are provided in context.return_methods.
"UPS Ground"
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.
Show child attributes
Show child attributes
The order information.
Show child attributes
Show child attributes
The unique identifier of the order.
42
The three-character ISO 4217 currency code.
"USD"
The line items in the order.
Show child attributes
Show child attributes
The unique identifier of the line item.
74
The product ID from the provider.
7804939829359
The variant ID from the provider.
43045586894959
The title of the product.
"Example Product"
The title of the variant.
"Example Variant"
The price of the item in minor units.
2250
The URL of the product image.
"https://example.com/example.jpg"
Line items from the order that can be returned. Use the order_line_item_id from this array when calling the add-returning-item action. Cross-reference with context.order.line_items for full item details.
Show child attributes
Show child attributes
The unique identifier created by Loop of the order line item.
74
Line items from the order that cannot be returned, along with the reason why. Common reasons include items past the return window, final sale items, or items already returned.
Show child attributes
Show child attributes
The unique identifier created by Loop of the order line item.
12347
The code indicating why the item is not eligible for return. Common codes: not_eligible_for_return, past_return_window, final_sale, already_returned.
"not_eligible_for_return"
Available return reasons that can be selected for returning items.
Show child attributes
Show child attributes
The unique identifier of the return reason.
1
The display name of the return reason.
"Too small"
Whether this reason requires an additional comment.
false
Available return shipping methods for this draft return.
Show child attributes
Show child attributes
The unique identifier of the return method.
1
The display name of the return method.
"UPS Ground"
The type of return method.
label, dropoff, pickup "label"
The cost of this return method in minor units (0 for free).
0
The shipping carrier name.
"UPS"
Valid credit types based on merchant configuration and return eligibility.
refund, gift, exchange Products available for exchange or shop-now during the return process.
Show child attributes
Show child attributes
The product identifier.
100
The product title.
"Red Shirt"
The product type/category.
"Apparel"
URL of the product image.
"https://cdn.example.com/products/red-shirt.jpg"
Available variants for this product.
Show child attributes
Show child attributes
The variant identifier.
501
The variant title (e.g., "Small / Red").
"Small"
The SKU of the variant.
"SHIRT-RED-S"
The price of the variant in minor units.
2500
Whether this variant is in stock and available.
true
HATEOAS links representing available actions for the current draft return state.
How to use links:
- Check the
relfield to identify the action - Review the
fieldsarray to see what data is required - Make an HTTP request to the
hrefusing the specifiedmethod - Include all fields marked with
is_required: true
State-based availability:
- In
createdstate: Links for adding items, setting customer, finalizing items - In
items-finalizedstate: 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
Show child attributes
Show child attributes
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").
The fully-qualified URL to call for this action.
The HTTP method to use when calling this link.
Human-readable description of what this action does.
"Add a line item to the return"
Optional user-facing prompt text for this action.
"Which item would you like to return?"
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_requiredto determine mandatory vs optional fields - Use
typefor client-side validation - Display
descriptionto end users for guidance - For enum types, use
allowed_valuesto populate dropdowns
Show child attributes
Show child attributes
The parameter name (snake_case).
"order_line_item_id"
The data type of the field. Common types: int, string, bool, enum.
"int"
Human-readable description of the field.
"ID of the line item to return"
For enum type fields, this contains the list of valid values.
["refund", "gift", "exchange"]Whether this field is required for the action to succeed.
true
Whether this action is required to progress the draft return. If true, the draft return cannot be submitted until this action is completed.
true
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.