Merchant API: returns and refunds v2.1 [beta]

This article describes the returns and refunds v2.1 endpoints in the Merchant API. 

If you do not participate in the returns and refunds v2.1 beta program, please use the returns v2 API endpoints. Check out Merchant API: main resources, Returns.

Table of contents

Introduction

Requirements

Limitations

Supported marketplaces

Setup

Returns

• Marketplace returns 2.1
• Merchant returns 2.1
• Marketplace-fulfilled returns 2.1

Refunds

• Marketplace refunds 2.1
• Merchant refunds 2.1

Marketplace return and refund support

FAQs

Introduction

The returns and refunds 2.1 endpoints support returns and refunds as two separate processes:

• Returns - the physical process of customers sending products back to the merchant.
• Refunds - the financial process of refunding the customer for any amount paid.

By decoupling the refunds process from the existing return process, you can refund order amounts in full or partially, without requiring the physical return of products.

To learn how to use the new returns and refunds feature via the web interface, check out the article ChannelEngine: returns and refunds [beta].

Requirements

You must already have an active API integration with ChannelEngine to start using the v2.1 returns and refunds workflows.

Limitations

• Mixing old and new workflows is not supported. Once you switch to returns and refunds v2.1, all return and refund handling must go through the new endpoints. You cannot combine v2.1 with the previous workflow.
• Channel support is limited. The v2.1 workflow is available on select channels. Before switching, confirm that your channels are listed in Supported marketplaces. For channels that do not support v2.1, returns and refunds must be managed manually on the channels' portals.
• Merchant API only. The v2.1 workflow requires a direct Merchant API connection. If you connect to ChannelEngine through a merchant plugin, this workflow is not available in your tenant.
• Refunds are issued in the original order currency only, including VAT and any applicable sales taxes.

Supported marketplaces

The table below shows the return and refund support levels per marketplace.

The above table contains six columns:

• Return support - the level of return support provided by the marketplace, as described in the Return support values.
• Import returns - whether ChannelEngine imports returns declared by the marketplace. This applies when the marketplace itself initiates a return on behalf of the buyer.
• Export returns - whether ChannelEngine exports returns to the marketplace. This applies when the merchant initiates a return on ChannelEngine and the marketplace needs to be notified.
• Refund support - the level of refund support provided by the marketplace, as described in the Refund support values table.
• Import refunds -  whether ChannelEngine imports refunds from the marketplace. This only applies where the marketplace makes a refund on behalf of the merchant.
• Export refunds - whether ChannelEngine can export refunds to the marketplace to trigger a refund on the buyer's order.

Setup

To use the returns and refunds 2.1 endpoints, contact your customer success manager or ChannelEngine’s Support team.

Returns

ChannelEngine’s Merchant API allows you to handle three types of returns:

• Marketplace returns - declared by the marketplace. 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, as it is a marketplace-fulfilled order. These are usually retrieved for reporting purposes.

Available API endpoints

Marketplace returns 2.1

When a marketplace declares a return, it notifies you that a returned product is on the way. When the product is received at your warehouse, you can:

• Retrieve marketplace returns: GET /v2.1/returns/merchant/

Use this endpoint with the filter creatorType=ONLY_CHANNEL to retrieve returns that were registered on the marketplace. These are the returns that a buyer registered with the marketplace but has not sent back to your return address yet. You can filter by date range to implement regular calls to this endpoint.

• Acknowledge returns: POST /v2.1/returns/merchant/acknowledge

Use this endpoint to acknowledge returns. Once you successfully receive a marketplace return in your system, mark it as acknowledged on ChannelEngine. This is important as it changes the return status from New to In progress on ChannelEngine, and allows for the addition of your internal identifier, MerchantReturnNo, so you can use it in any subsequent calls.

• Handle returns: POST /v2.1/returns/merchant/handle

Use this endpoint to decide on the best way to handle the return. Choose an action – refund, repair, exchange, keep, or reject. If you choose the refund action, ChannelEngine automatically creates a refund for the full value of the returned products. Alternatively, use the bulk-handle endpoint to handle multiple returns in one request. 

• Create or update return extra data: PATCH /v2.1/returns/merchant/extra-data

Use this endpoint to create or update extra data for a return. Only extra data created by the merchant can be updated. Extra data created by the marketplace or ChannelEngine cannot be modified.

You can add extra data at two levels:

• To the overall return
• At the order line level, i.e.: for a specific returned product

If the extra data applies to the full return, provide a unique identifier for your return using the ReturnIdentifier. If the extra data applies to the return of a specific product within the return, assign a unique identifier using the ReturnLineIdentifier. Provide the Key of the extra data to be created or updated, followed by its Value. 

Merchant returns 2.1

Some marketplaces do not offer the option to register returns directly. In this case, you have to provide a return form in the parcel or submit your own return policy to the marketplace, so the buyer knows how they can return the item. To handle a return directly with the buyer, you must first create it on ChannelEngine.

• Create returns: POST /v2.1/returns/merchant/

Use this endpoint to create returns that the buyer handled directly with you. Provide the quantity of products per order line that you accept as returned and indicate the reason for the return. E.g.: defect, wrong size, etc.

If you include the MerchantReturnNo, the return is created with the status In progress and is automatically acknowledged. You can, however, leave out the MerchantReturnNo, to create a return in the status New. This is useful if you plan to retrieve and acknowledge this return later through another system, such as your OMS or ERP.

Bear in mind that some marketplaces only allow full, not partial returns. But if the marketplace supports it, parts of an order can be returned and several returns for the same order can be created.

If the marketplace does not support returns, ChannelEngine automatically converts it to a refund.

Once you create a return on ChannelEngine, you need to properly handle it via the POST /v2.1/returns/merchant/handle endpoint.

• Create or update return extra data: PATCH /v2.1/returns/merchant/extra-data

Use this endpoint to create or update extra data for a return. Only extra data created by the merchant can be updated. Extra data created by a channel or ChannelEngine cannot be modified.

You can add extra data at two levels:

• To the overall return
• At the line level, i.e.: for a specific returned product

If the extra data applies to the full return, provide a unique identifier for your return using the ReturnIdentifier. If the extra data applies to the return of a specific product within the return, assign a unique identifier using the ReturnLineIdentifier. Provide the Key of the extra data to be created or updated, followed by its Value. 

Marketplace-fulfilled returns 2.1

• Retrieve marketplace-fulfilled returns: GET /v2.1/returns/merchant/

Use this endpoint with the filter fulfillmentType=ONLY_CHANNEL to retrieve returns of marketplace-fulfilled orders. These returns are handled completely by the marketplace itself. However, you can use these for reconciliation purposes.

Refunds

ChannelEngine’s Merchant API allows you to handle two types of refunds:

• Marketplace refunds - declared by the marketplace. E.g.: the buyer consults the marketplace's customer service or requests the refund on the marketplace's website.
• Merchant refunds - declared by you. E.g.: the buyer consults your customer service and asks for a refund.

Available API endpoints

Marketplace refunds 2.1

• Retrieve marketplace refunds: GET /v2.1/refunds/merchant

Use this endpoint with the filter creatorType=ONLY_CHANNEL to retrieve refunds that were registered on the marketplace side. You can filter by date range to implement regular calls to this endpoint. After retrieving a marketplace refund, you can mark it as acknowledged and decide on the best way to handle it.

• Handle refunds: POST /v2.1/returns/merchant/handle

Use this endpoint to decide on the best way to handle the refund. Choose an action – refund, repair, exchange, keep, or reject. If you choose the refund action, ChannelEngine automatically creates a refund for the full value of the returned products.

• Acknowledge refunds: POST /v2.1/refunds/merchant/acknowledge

Use this endpoint to acknowledge refunds. Once you retrieve the refund from the marketplace, you can mark it as acknowledged on ChannelEngine. This action is optional; however, it is useful as it allows for the addition of identifiers, such as the MerchantRefundNo, so you can keep track of the refund throughout the workflow.

Merchant refunds 2.1

• Issue refunds: POST /v2.1/refunds/merchant

Use this endpoint to issue a refund for the product. Specify the order ID, order lines, and the amount to be refunded. You must also provide a unique identifier for your refund using the MerchantRefundNo field. This allows you to keep track of the refund. The same goes for each order line – assign a unique identifier using MerchantRefundLineNo.

After you create a refund, ChannelEngine first checks if the marketplace supports direct refunds. If those are supported, a refund is automatically created on ChannelEngine, and no further action is required. If the marketplace does not support direct refunds but supports returns, ChannelEngine creates a return for the refunded product. The refund action then marks the return as Handled.

If the marketplace rejects a refund, its status changes to Rejected. You must then process the refund manually. If the refund is accepted, its status changes to Processed.

• Create or update extra data: PATCH /v2.1/refunds/merchant/extra-data

Use this endpoint to create or update extra data for a refund. Only extra data created by the merchant can be updated. Extra data created by a channel or ChannelEngine cannot be modified.

You can add extra data at two levels:

• To the overall refund
• At the order line level, i.e.: for a specific refunded product

If the extra data applies to the full refund, provide a unique identifier for your refund using the RefundIdentifier. If the extra data applies to the refund of a specific product within the refund, assign a unique identifier using the RefundLineIdentifier. Provide the Key of the extra data to be created or updated, followed by its Value. 

Marketplace return and refund support

Marketplaces vary in their support for returns and refunds. Return support describes whether a return can be declared and who can initiate it. Refund support describes what kind of refund is permitted once a return is processed. Both values are returned per order via the /v2/orders endpoint.

The tables below explain each possible value, followed by a per-marketplace overview.

Return support values

Refund support values

FAQs

Which endpoint should I use to receive the value of a returned item?
To retrieve the value of a returned item via the Merchant API, note down the orderID of the returned item from the GET /v2.1/returns/merchant/ response. Then, use the orderID as a query parameter in the GET /v2.1/refunds/merchant. The relevant price fields for the returned item appear in the refund request response.