Skip to main content

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: An example draft return response is shown below.
Draft return object

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

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

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

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
If there are eligible items, they can be added to the return using the Add Returning Item endpoint.
Add returning item

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

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

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

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

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
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
The finalized version of the draft return is returned. Note that there are no linked actions in the links object.
Submitted draft return

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