> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.loopreturns.com/api-reference/authentication.md).

## 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.

```json Draft return object theme={null}
{
    "draft_return": {
        "id": 43,
        "state": "created",
        "currency": "USD",
        "language": "en",
        "credit_type": null,
        "customer": {
            "email": "first.last@example.com"
        },
        "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",
            "original_payment_transactions": [
                {
                    "type": "sale",
                    "gateway": "shopify_payments",
                    "amount": 999,
                    "currency": "USD",
                    "brand": "visa",
                    "last4": 4242
                }
            ],
            "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

> [!NOTE]
>
> 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:

1. **Exchange Items**: When a shopper wants to exchange their returned item for a different product or variant.
2. **Replacement Items**: When a shopper needs a replacement for a defective or damaged item.
3. **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.

```mermaid theme={null}
flowchart TD
    A((Start)) -->|Initialize draft return| B{Is the return a gift?}
    B -->|Yes| C([Set customer])
    B -->|No| F([Returning items])
    C --> D([Set address])
    D --> F
```

#### Initialize Draft Return

Creating a draft return begins with the [Initialize Draft Return](https://docs.loopreturns.com/api-reference/latest/draft-returns/initialize-draft-return.md) 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.

```curl Initialize draft return theme={null}
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](https://docs.loopreturns.com/api-reference/latest/draft-returns/set-customer.md) and [Set Address](https://docs.loopreturns.com/api-reference/latest/draft-returns/set-address.md) 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](https://docs.loopreturns.com/api-reference/latest/draft-returns/get-draft-return.md) endpoint.

```curl Get draft return theme={null}
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.

```mermaid theme={null}
flowchart TD
    A([Returning items]) -->|Eligible items > 0| B([Add returning item])
    B --> C([Set return reason])
    C --> D([Set return type])
    D -->|More items to return| A
    D -->|No more items| E([Proceed to checkout])
    A -->|No eligible items| F((Cancel return))
```

#### 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.

```json Eligible and ineligible items theme={null}
"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](https://docs.loopreturns.com/api-reference/latest/draft-returns/add-returning-item.md) endpoint.

```curl Add returning item theme={null}
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](https://docs.loopreturns.com/api-reference/latest/draft-returns/set-returning-item-return-reason.md) to collect the parent and child reason for each item.

> [!NOTE]
>
> 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.

```curl Set returning item return reason theme={null}
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](https://docs.loopreturns.com/api-reference/latest/draft-returns/set-returning-item-return-type.md) endpoint.

```curl Set returning item return type theme={null}
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.

```mermaid theme={null}
flowchart TD
    A([Returning items]) -->|Has items to return| B([Add cart items])
    B --> G(Repeat as needed)
    G --> B
    B -->|Cart complete| C([Finalize items])
    C --> D{Refund eligible?}
    D -->|Yes| E([Set credit type])
    D -->|No| F([Proceed to return method])
    E --> F
```

#### 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](https://docs.loopreturns.com/api-reference/latest/draft-returns/add-returning-item-exchange-item.md) endpoint.

```curl Add returning item exchange item theme={null}
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](https://docs.loopreturns.com/api-reference/latest/draft-returns/finalize-items.md) endpoint to finalize the draft return's contents.

> [!NOTE]
>
> The Finalize items endpoint still needs to be called even if the draft return doesn't include any cart items.

```curl Finalize items theme={null}
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

> [!NOTE]
>
> 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](https://docs.loopreturns.com/api-reference/latest/draft-returns/set-credit-type.md) 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).

```curl Set credit type theme={null}
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.

```mermaid theme={null}
flowchart TD
    A([Returning items]) -->|Has items to return| B([Select return method])
    B --> C{Requires carrier?}
    C -->|Yes| D([Set carrier])
    C -->|No| E([Submit return])
    D --> E
```

#### Available Return Methods

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

```curl Return method options theme={null}
"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](https://docs.loopreturns.com/api-reference/latest/draft-returns/select-return-method.md) 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](https://docs.loopreturns.com/api-reference/latest/draft-returns/submit-draft-return.md) endpoint.

```curl Submit draft return theme={null}
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.

```json Submitted draft return theme={null}
{
    "draft_return": {
        "id": 43,
        "state": "submitted",
        "currency": "USD",
        "language": "en",
        "credit_type": "refund",
        "customer": {
            "email": "first.last@example.com"
        },
        "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",
            "original_payment_transactions": [
                {
                    "type": "sale",
                    "gateway": "shopify_payments",
                    "amount": 999,
                    "currency": "USD",
                    "brand": "visa",
                    "last4": 4242
                }
            ],
            "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](https://docs.loopreturns.com/api-reference/latest/draft-returns/cancel-draft-return.md) endpoint. A draft return can be cancelled at any time.

```curl Cancel draft return theme={null}
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'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.