Merchant API: returns

About this article

This article is about how to manage returns via the Merchant API v2 endpoints.

Table of contents

Introduction

Available API endpoints

• Create a merchant return
• Retrieve marketplace returns
• Retrieve marketplace-fulfilled returns
• Acknowledge a return
• Mark a return as received

Test returns

Introduction

ChannelEngine’s Merchant API v2 endpoints allow you to handle three types of returns:

• Marketplace returns - declared by the marketplace (i.e.: channel). E.g.: the buyer consults the marketplace's customer service or requests the return on the channel's website. 
• Merchant returns - declared by you. E.g.: the buyer consults your customer service.
• Marketplace-fulfilled returns - declared and handled by the marketplace. These are usually retrieved for reporting purposes.

Available API endpoints

Create a merchant return

• Merchant returns: POST /v2/returns/merchant

Use this endpoint to create a return that the buyer returned directly with you (and not via the marketplace). Provide the quantity of products per order line that you accept as returned. 

Refunds

You can also submit the refund amount, inclusive and exclusive of taxes. However, please note that the marketplace typically calculates the refund amount based on the quantity you provided. 

Partial returns

If the marketplace supports it, parts of an order can be returned, and several returns for the same order can be created.

Retrieve marketplace returns

• Marketplace returns
  • GET /v2/returns/merchant
  • GET /v2/returns with the filter creatorType=ONLY_FROM_CHANNEL 
  • GET /v2/returns/merchant/new 

To retrieve all marketplace returns, use GET /v2/returns/merchant 

To retrieve all marketplace returns with the flexibility of posting your request with a variety filters, use GET /v2/returns with the filter creatorType=ONLY_FROM_CHANNEL. Filter by date and time to regularly request marketplace returns from this endpoint.

Alternatively, use GET /v2/returns/merchant/new to retrieve returns that the buyer registered directly via the marketplace but are not yet on their way back to your warehouse.

Retrieve marketplace-fulfilled returns

• Marketplace-fulfilled returns
  • GET /v2/returns/merchant  
  • GET /v2/returns with the filter fulfillmentType=ONLY_CHANNEL

Retrieve the returns of channel-fulfilled orders for reconciliation purposes by calling the endpoint GET /v2/returns/merchant. 

Alternatively, call GET/v2/returns with the following filters: 

• creatorType=ONLY_FROM_CHANNEL 
• fromDate 
• fulfillmentType set to ONLY_CHANNEL for channel-fulfilled orders or 
• fulfillmentType set to MIXED for mixed orders

Acknowledge a marketplace return

• Acknowledge a return: POST /v2/returns/merchant/acknowledge

To process marketplace returns, first retrieve them (typically in New status) and then acknowledge them. Acknowledgement allows you to add your own MerchantReturnNo (your internal return number). Adding your merchant return number is important so you can reference the same return in later API calls and in your internal processes, e.g.: refund/repair/exchange. 

To acknowledge marketplace returns:

1. Call the GET /v2/returns/merchant endpoint.
2. Use the following parameters:
   • statuses - in_progress
   • isAcknowledged - false
   • fromDate - enter the date from which you want to start acknowledging returns.
3. Call the POST /v2/returns/merchant/acknowledge endpoint to acknowledge new returns.

To acknowledge marketplace-fulfilled returns:

1. Call the GET /v2/returns/merchant endpoint.
2. Use the following parameters:
   • fulfillmentType - ONLY_CHANNEL
   • isAcknowledged - false
3. Call the POST /v2/returns/merchant/acknowledge endpoint to acknowledge new returns.

Mark a return as received

• Mark a return as received: PUT /v2/returns

Once you receive the return at your warehouse or other return address, mark it as received via the PUT /v2/returns endpoint. In the request body: 

• Indicate the quantity you accept -  AcceptedQuantity
• Indicate the the quantity you reject - RejectedQuantity. 
• AcceptedQuantity plus RejectedQuantity must equal the full quantity of the incoming return. The buyer is refunded based on the accepted quantity. 

Make certain that you accept and reject the correct quantities; you cannot update a marketplace return more than once.

Test returns

While setting up your API connection, it can be useful to test out your requests with test returns. You can create test marketplace returns on the ChannelEngine web interface. For guidance on using test orders and test marketplace returns to test your requests, check out ChannelEngine: how to create a test marketplace return and Merchant API: testing flow.