Getting Started with the Return Create API

Overview

The Return Create API lets you create returns in Loop without using the Loop shopper portal. It’s ideal for integrating Loop’s return management system into custom storefronts or third-party apps that need to offer return functionality directly.

Requirements

The Return Create API may not be available on all Loop plans. Consult with your integrating partner or your Loop point of contact to determine if this feature is included with the API key you’re working with.

Setup

To get started with the Return Create API, you’ll first need an 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.

Core Concepts

Draft Return Object Structure

Draft return objects are composed of four constituent parts:

Object	Description
`draft_return`	This object contains information about the draft return and the shopper who created it.
`context`	This object contains the information needed to fill in the payloads of the actions described in the links.
`links`	This object contains an array of the next possible actions that can be performed on the draft return in its current state.
`errors`	This object contains an array of any errors encountered by the draft return service while processing the return.

An example draft return response is shown below.

Draft return object

{
    "draft_return": {
        "id": 43,
        "state": "created",
        "currency": "USD",
        "language": "en",
        "credit_type": null,
        "customer": {
            "email": "[email protected]"
        },
        "shipping_address": {
            "name": "First Lastman",
            "company": null,
            "address1": "123 Example Street",
            "address2": null,
            "city": "Townsville",
            "state": "Ohio",
            "zip": "43215",
            "country": "United States",
            "country_code": "US",
            "phone": "678 999 8212"
        },
        "returning_items": [],
        "cart_items": [],
        "selected_return_method": null
    },
    "context": {
        "order": {
            "id": 110880133,
            "currency": "USD",
            "line_items": [
                {
                    "id": 291523857,
                    "provider_product_id": 9043184189686,
                    "provider_variant_id": 48400944201974,
                    "title": "Example Item",
                    "variant_title": null,
                    "price": 999,
                    "image": "https://example.com/example-image.jpg"
                }
            ]
        },
        "items_eligible_to_return": [
            {
                "order_line_item_id": 291523857
            }
        ],
        "items_not_eligible_to_return": []
    },
    "links": [
        {
            "rel": "add-returning-item",
            "href": "https://api.loopreturns.com/api/v1/2479/draft-returns/43/returning-items",
            "method": "POST",
            "fields": [
                {
                    "name": "order_line_item_id",
                    "type": "int",
                    "description": "ID of the line item to return",
                    "is_required": true
                }
            ],
            "is_required": true
        }
    ],
    "errors": []
}

Cart

The cart is only relevant when dealing with exchanges and upsell scenarios. Returns using the refund flow that don’t involve an item being shipped to the shopper don’t use the cart.

The cart is a fundamental concept in the Return Create API that represents items that will be sent to the shopper as part of resolving their return. The cart serves several important purposes:

Exchange Items: When a shopper wants to exchange their returned item for a different product or variant.
Replacement Items: When a shopper needs a replacement for a defective or damaged item.
Additional Purchases: When a shopper wants to add new items to their return order.

The cart is represented in the draft return object as cart_items, which is an array of items that will be sent to the shopper. Each cart item includes:

Product variant ID
Quantity
Price information
Any applicable discounts or credits

The cart can be modified throughout the return creation process until the items are finalized. Once finalized, the cart contents cannot be changed without starting a new return.

API Workflow

1. Initial Setup

This phase covers creating the draft return and setting up customer information for gift returns.

Initialize Draft Return

Creating a draft return begins with the Initialize Draft Return endpoint. At this stage, the draft return is associated with a shop ID and an order name from that shop. The customer and address information for the return is also automatically populated for non-gift 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 '{
    "shop_id": 23141001,
    "order_name": "#1001",
    "secondary_input": "90210",
    "is_gift": false
    }'

Set Customer Information

Customer and address information is populated automatically unless the return is using the Gift flow (indicated by setting the is_gift parameter to true when initializing the draft return). For returns using the Gift flow, set the customer and address information using the Set Customer and Set Address endpoints.

Get Draft Return Status

At any point during the return creation process, the current state of the draft return can be accessed 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
}'

2. Return Details

In this phase, you’ll add items to the return and collect information about why they’re being returned.

Add Returning Items

At this stage in the draft return flow, check the lists of eligible and ineligible returning items returned as part of the draft return object.

Eligible and ineligible items

"items_eligible_to_return": [
    {
        "order_line_item_id": 291523857
        }
    ],
"items_not_eligible_to_return": []

If there are eligible items, they can be added to the return using the Add Returning Item endpoint.

Add returning item

curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/returning-items \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --header 'X-Shop-Id: 23141001' \
  --data '{
  "order_line_item_id": 291523857
}'

Set Return Reasons

After that, return reason data can be collected using Set Returning Item Return Reason to collect the parent and child reason for each item.

The action of setting the child return reason will have a rel of set-returning-item-specific-return-reason rather than set-returning-item-return-reason, but the URL for the action remains the same.

Set returning item return reason

curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/returning-items/{returning_item_id}/return-reason \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '{
  "reason_id": 50211
}'

Set Return Types

The return type (credit or exchange) should also be set for each returning item using the Set Returning Item Return Type endpoint.

Set returning item return type

curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/returning-items/{returning_item_id}/return-type \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '{
  "return_type": "credit"
}'

3. Checkout Process

The checkout phase handles exchange items, finalizes the cart, and sets the credit type for the return.

Cart Management

The cart is a concept used to represent any items that will be sent to the shopper as part of resolving the return (for example, a replacement or exchange item). If the draft return is an exchange, add exchange items using the Add Returning Item Exchange Item endpoint.

Add returning item exchange item

curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/returning-items/{returning_item_id}/exchange-item \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --header 'X-Shop-Id: 23141001' \
  --data '{
        "variant_id": 12345
}'

Once all items involved in the return or exchange have been added use the Finalize Items endpoint to finalize the draft return’s contents.

The Finalize items endpoint still needs to be called even if the draft return doesn’t include any cart items.

Finalize items

curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/finalize-items \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '{
}'

Credit Type Selection

This step is only applicable to returns with the credit return type. The credit type for draft returns using the exchange flow is automatically set to exchange.

Once all items have been finalized, select the credit type for the return using the Set Credit Type endpoint. The possible credit options are refund (which uses the shopper’s original payment method), gift (which issues a gift card), or exchange (for exchange transactions).

Set credit type

curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/credit-type \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '{
  "credit_type": "refund"
}'

4. Return Method Selection

This phase allows the customer to choose how they’ll return their items to the merchant.

Available Return Methods

A list of return methods is returned as part of the draft return object.

Return method options

"return_method_options": 
[
    {
        "id": 33,
        "name": "happy-returns",
        "type": "drop-off",
        "fees": 
        {
            "amount": 33
            }
        },
    {
        "id": 34,
        "name": "purchase-label",
        "type": "box-and-ship",
        "fees": 
        {
            "amount": 33
            }
        }
    ]

By default, the last return method listed will be selected for the return. You can specify a different return method using the Select return method endpoint.

5. Finalization

Submit Draft Return

Once all returning items that will be sent back to the merchant are associated with a return method, the draft return can be submitted using the Submit Draft Return endpoint.

Submit draft return

curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/submit \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '{
}'

The finalized version of the draft return is returned. Note that there are no linked actions in the links object.

Submitted draft return

{
    "draft_return": {
        "id": 43,
        "state": "submitted",
        "currency": "USD",
        "language": "en",
        "credit_type": "refund",
        "customer": {
            "email": "[email protected]"
        },
        "shipping_address": {
            "name": "First Lastman",
            "company": null,
            "address1": "123 Example Street",
            "address2": null,
            "city": "Townsville",
            "state": "Ohio",
            "zip": "43215",
            "country": "United States",
            "country_code": "US",
            "phone": "678 999 8212"
        },
        "returning_items": [
            {
                "id": 28,
                "order_line_item_id": 291523857,
                "return_type": "credit",
                "return_reason": {
                    "name": "I didn't like the packaging"
                },
                "user_input": []
            }
        ],
        "cart_items": [],
        "selected_return_method": {
            "id": 34,
            "name": "purchase-label",
            "type": "box-and-ship"
        }
    },
    "context": {
        "order": {
            "id": 110880133,
            "currency": "USD",
            "line_items": [
                {
                    "id": 291523857,
                    "provider_product_id": 9043184189686,
                    "provider_variant_id": 48400944201974,
                    "title": "Example Item",
                    "variant_title": null,
                    "price": 999,
                    "image": "https://example.com/example-image.jpg"
                }
            ]
        }
    },
    "links": [],
    "errors": []
}

Cancel Draft Return

If there are neither eligible items nor returning items, the draft return can’t be submitted and should be cancelled using the Cancel Draft Return endpoint. A draft return can be cancelled at any time.

Cancel draft return

curl --request POST \
  --url https://api.loopreturns.com/api/v1/draft-returns/{draft_return_id}/cancel \
  --header 'X-Authorization: <api-key>' \
  --header 'X-Shop-Id: 23141001'

Introduction

Guides

Use Cases

Return Create

Overview

Requirements

Setup

Core Concepts

Draft Return Object Structure

Cart

API Workflow

1. Initial Setup

Initialize Draft Return

Set Customer Information

Get Draft Return Status

2. Return Details

Add Returning Items

Set Return Reasons

Set Return Types

3. Checkout Process

Cart Management

Credit Type Selection

4. Return Method Selection

Available Return Methods

5. Finalization

Submit Draft Return

Cancel Draft Return

Introduction

Guides

Use Cases

Return Create

​Overview

​Requirements

​Setup

​Core Concepts

​Draft Return Object Structure

​Cart

​API Workflow

​1. Initial Setup

​Initialize Draft Return

​Set Customer Information

​Get Draft Return Status

​2. Return Details

​Add Returning Items

​Set Return Reasons

​Set Return Types

​3. Checkout Process

​Cart Management

​Credit Type Selection

​4. Return Method Selection

​Available Return Methods

​5. Finalization

​Submit Draft Return

​Cancel Draft Return

Overview

Requirements

Setup

Core Concepts

Draft Return Object Structure

Cart

API Workflow

1. Initial Setup

Initialize Draft Return

Set Customer Information

Get Draft Return Status

2. Return Details

Add Returning Items

Set Return Reasons

Set Return Types

3. Checkout Process

Cart Management

Credit Type Selection

4. Return Method Selection

Available Return Methods

5. Finalization

Submit Draft Return

Cancel Draft Return