Returnly Integration API

Contents

1. Overview
2. About Returnly
3. APIs
   • Returnly API
   • Integration API
4. Integration API v2
   • Module 1: Order  
   • Module 2: Refund
   • Module 3: Voucher
   • Module 4: Exchange
   • Authentication

 

Overview

For merchants on custom-built platforms

With our Integration API modules, merchants on custom platforms would be able to easily and quickly integrate with Returnly.

This article covers a brief introduction to our Return Manager, our APIs and Webhooks, and how you can leverage our Integration API based on your business needs. 

About Returnly

Returnly is a returns management software & financial technology platform that offers shoppers a seamless online product returns experience. 

Returnly’s two main products are: 

• Returnly Suite: An end-to-end returns management platform that enables easy returns for customers and merchants, maximizing customer convenience and reducing support costs.
• Returnly Credit: Returnly’s financial technology creates a new revenue stream for merchants by increasing sales through the online product returns flow. Returnly Credit includes Instant Exchanges and Instant Credit. 

To be able to seamlessly connect Returnly to any system, Returnly offers API and Webhook integration solutions. Thus, merchants are able to accomplish more automation that otherwise would require manual intervention. 

 

This document covers the following:

• Brief overview of Returnly APIs and Webhooks
• How merchants on custom platforms can leverage Returnly Integration API

 

APIs & Webhooks

Term	Definition
API	Application Programming Interface APIs are interactive, where one party makes a request and gets a response.
Webhooks	They are event driven and are a unidirectional model. A “Send it and forget it”.

 

Benefits

Returnly provides these resources in order to help merchants create seamless experiences for their shopper experience and operations. 

• Allow custom merchants to build and use Returnly.
• Merchants who have ERPs can use our capabilities to get automatically updated as returns are created & updated.
• Allow merchants to accomplish automation we do not natively support through current platform capabilities.

 

APIs

Key Terms 

The table below shows key terms which would be used throughout the Returnly Developer Portal. 

Term	Description
Returnly Return Center	Used by customers to start a return.
Returnly Dashboard Or Return Manager	Used by merchants to manage returns.
Product	A product refers to the physical/virtual item sold to a customer. Merchants configure product catalogs in different ways.
Variant	Option that can be configured under a single product ID in your eCommerce platform. Some products may have different variants. For example, a t-shirt (product) might have size variants XS, S, M, L and XL. Note: There could be products which would not have any variants. Example: paintings.
Order	An order is an entity that represents a customer’s purchase of several products/variants (order lines).  Orders are usually placed by customers on merchants either online or at a brick and mortar store but can be also created by Returnly on exchanges on behalf of the customer.
Order line	An order is composed of order lines that identify different products/variants. Each order line has a unit value. Example:  Order 1: 2 black t-shirts and 3 white ones. Order line 1 with 2 units Order line 2 with 3 units
Draft order	Represents an unprocessed (draft) order or shopping cart.
Exchange	Act of giving one product variant and receiving another one in return. Example: If you’ve bought a white t-shirt in a shop, you can go to the brick-and-mortar store to return it and get the black variant in exchange. This will result in 2 orders:  One order for the white t-shirt Another order for the black one
Return	A return identifies a customer’s willingness to return products back to the merchant in order to be refunded.  A return may have between one or many products from one or  several orders.
Green returns	A type of return in which the customer doesn’t have to return the product to the merchant.
Voucher / Gift Card	A discount that may be used when buying on any of the merchant’s channels whether that is online or at a brick-and-mortar store.
Refund	Repayment to a customer who has returned an item.  The refund could be made to either the original payment method or a gift card.

 

 

Returnly API

Versioning: Returnly API v2020-08

Eligibility: Any merchant on any eCommerce platform that has an API key generated.

Note: Merchants on a Returnly's Premium Plan (Annual) can generate their API token by accessing the Integration Tools page, API Token tab on their Returnly Dashboard. Merchants on a Monthly plan should reach out to sales@returnly.com to upgrade their account.

Merchants have external systems that they utilize to run their operations that require programmatic retrieval or delivery of Returnly data.

With the Returnly APIs, any eligible merchant or partner is able to retrieve data about returns, review refund requests, and trigger refunds.

Returnly API suite has three endpoints: 

Returns API

• The Returns API allows merchants to retrieve information or modify properties of existing returns.

Refunds API

• The Refunds API solves for the problem where a merchant wants to automate refunding of specific RMAs.

Refund Requests API

• Merchants can check the status of their refunds by calling the Refund Request API. This endpoint can be used to troubleshoot external applications that are making bad APIs.

 

Integration API

For those businesses built on custom-built platforms looking to leverage Returnly API and start delivering value to their customers. 

Currently supporting two versions.

Returnly Integration API v1: For existing merchants that have partnered with Returnly prior to January 18th, 2023.

Returnly Integration API v2: For merchants partnering with Returnly from January 18th, 2023.

Merchants on custom platforms can have one of the following scenarios:

• Instant Credit & Exchanges disabled
• Instant Credit & Exchanges enabled
• Instant Credit enabled & Exchanges disabled
• Instant Credit disabled & Exchanges enabled

Based on your business needs, below are the modules so as to seamlessly integrate with Returnly, where the first two modules (Order and Refund) are the minimum implementation requirements. 

Module 1: This is the only call merchants make to Returnly. 

• • Order

Modules 2 to 4: Calls made by Returnly to the merchant. 

• • Refund
  • Voucher
  • Exchange

 

Return Flow Overview: Endpoints Sequence

Note: Order of Modules and API calls must be followed as shown.

 

Module 1: Order  

Merchants should post orders to Returnly when they are created.  The orders will be then available to Returnly when the shopper initiates a return.  

Order: An order is composed of order lines that identify different products/variants. Then, shoppers can initiate product(s) return(s) based on those orders. 

Once this module is implemented, shoppers will be able to return items. 

Required

• POST /external/ingestion_api: Provides Returnly with data needed to initiate a shopper return.

 

Module 2: Refund

Once merchants have posted newly-created orders, Returnly will be calling the following endpoints so merchants will be able to issue refunds on the return items.

Required for merchants on Instant Credit; Optional for other merchants

• POST /orders/{order_id}/refund_estimate: Returns a refund estimate for the line items requested before a refund is issued.
• POST /orders/{order_id}/refund: Issues refund to the shopper.

Note: Order of API calls must be followed as shown.

 

Module 3: Voucher

Once modules 1 and 2 are completed, merchants on Instant Credit will be able to implement module 3. This Voucher module enables Returnly to offer shoppers Instant Credit which they can use to create instant repurchases.

Required for merchants on Instant Credit

• • POST /vouchers: Provision a voucher. Merchant’s endpoint creates a voucher when a shopper initiates a return or when a refund is issued to a gift card.
  • GET /vouchers/{voucher_id}: Find voucher. Merchant’s endpoint finds a voucher.
    
  • POST /vouchers/{voucher}/disable: Disable voucher. Merchant’s endpoint disables a voucher. A return has been refunded without using the associated gift card generated when the return was created by the shopper.

Note: Order of API calls must be followed as shown.

 

Module 4: Exchange

Once module 3 is completed, merchants will be able to implement the Exchange module which enables shoppers to make instant variant exchanges.

If this option has been configured for a specific merchant, shoppers may have the option to exchange the product variant they are returning for another one.

Required to offer exchanges

• GET /products/{product_id}: Product Variants. This endpoint retrieves product variants in order to suggest those variants to shoppers. 
• POST /draft_order: Create Draft Order. Returnly creates a draft order which mitigates failures at order ingestion.
• POST /draft_order/{draft_order_id}/complete: Promote Order. Returnly completes a draft order on behalf of the shopper.

 

Scenarios:

For an instant variant exchange: Post Complete Draft Order is called after Post Draft Order. 

For automated exchanges: the Post Draft Order is called when the shopper completes the return, i.e. once the package has been scanned by the shipping carrier.

• POST /draft_order/{draft_order_id}/cancel: Cancel Order. Returnly cancels a pending draft order that hasn’t yet been promoted to an order. 

Note: Order of API calls must be followed as shown.

 

Authentication

By means of authentication protocols a receiving entity is able to verify the identity of another entity. 

 

Ingest Order Endpoint

The Ingest Order endpoint requires that the implementation pass a token for authentication. Merchants can generate their API token by accessing the Integration Tools page, API Token tab on their Returnly Dashboard.

 

All Other Endpoints

For all other endpoints, Returnly will call the implemented API endpoints throughout the return processing life-cycle.

These endpoints must implement one of four possible authentication protocols:

• NONE (Only for testing purposes)
• BASIC
• TOKEN
• OAUTH2

 

Considerations:

• Each endpoint can be configured separately.

Endpoints can have different authentication protocols, for which implementers need not implement the same authentication scheme for every endpoint.

Should you need assistance configuring your endpoints appropriately, contact our Merchant Care team at support@returnly.com.

 

NONE (No Authentication)

For testing purposes only.

 

BASIC Authentication

Basic Authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization Header that contains a Header Name and a Header Value. 

 

Header Name	Authorization
Header Value	“basic”  base64-encoded string of username:password The word “basic” followed by a space and a base64-encoded string of username and password separated by a colon, which would be as follows username:password.

 

TOKEN Authentication

With Token Authentication, the implementer provides a Token Name, and an Access Key value. The endpoint can be configured to send Token Name/Access Key values either as HTTP Header parameters, or as Query string parameters.

Required configuration values

Token Name (Param/Header Name)

Access Key (Authentication Token)

 

OAUTH2 Authentication

OAuth 2 authentication authenticates per the OAuth 2.0 Specification. Implementations must provide the endpoint of an authorization service provider, a client ID and secret.

Required configuration values

Authorization service provider endpoint (Authentication URL)

Client ID (Consumer Key)

Client Secret (Consumer Secret)

 

For any further details on our Integration API, contact our Merchant Care team at support@returnly.com to ensure a seamless integration experience.

Back To Top

---

 

+ Related: Returnly API Overview