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

Limitations

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

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

Limitations

• Combining elements of the old and new workflows is not allowed.
• Refunds are currently only issued in the order's original currency. Refunds include VAT and any applicable sales taxes.

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. Some support partial refunds, others only full refunds. To return the level of return and refund support for each order, use the /v2/orders endpoint.

Return and refund support shown in the /v2/orders response