Buyer Initiated Returns


Beta Preview Feature

The Buyer Initiated Returns (via API) feature is in beta and has been released for developer feedback.

About Buyer Initiated Returns

  • What is a Buyer Initiated Return
    • The concept allows buyers to request and initiate a return - sometimes without much involvement from the seller (but based on what the seller allows for their orders).
  • ChannelAdvisor supports a limited number of marketplace Buyer Initiated Returns processes - Jet and eBay are the only two as of July 2017.
    • Some marketplaces will allow automatically approved Buyer Initiated Returns - settings to allow this exist at the marketplace.
  • For sellers using a marketplace that uses Buyer Initiated Returns, this is the process to work with it via API.

    • RMA Number and Seller Adjustment ID (both optional) can be set through API with a separate request.
  • API is not the only method to handle Buyer Initiated Returns - customer service team members can execute all of this through the User Interface.

  • Build out a process that checks for Buyer Initiated Return requests every 4-6 hours (minimum once a day) to ensure any requests are handled within a timely manner.
  • A process should also be enabled from fulfillment partners to update the Buyer Initiated Return status once the package has been reviewed - either rejecting or approving the return.

Buyer Initiated Return API Process in ChannelAdvisor

  1. Buyer requests a return through the marketplace via the Buyer Initiated Returns process.
  2. Within 30 minutes, ChannelAdvisor picks up the request and creates an adjustment on that order:
    1. If the request is for the entire order, the adjustment will be created on order level.
    2. If the request is for a specific item or items, the adjustment will be created on the items in the order.
  3. Automated processes should check for both order-level adjustments and item-level adjustments (this cannot be made in one request):
    1. Order Level Buyer Initiated Return Check: GET /v1/Orders?$filter=Adjustments/Any (c:c/RequestStatus eq 'NewRma') or Adjustments/Any (c:c/RequestStatus eq 'ReadyForReturn') 
    2. OrderItem Level Buyer Initiated Return Check: GET /v1/OrderItems?$filter=Adjustments/Any (c:c/RequestStatus eq 'NewRma') or Adjustments/Any (c:c/RequestStatus eq 'ReadyForReturn') 
    3. Note: if marketplace settings automatically approve any Buyer Initiated Return, ChannelAdvisor imports those orders with RequestStatus = 'ReadyForReturn'. The requests will capture these as well.
  4. The seller needs to decide how to handle the Buyer Initiated Returns at two different stages - and an update will need to be made to the order to account for this action.
    Available actions vary based on the current status of the request:
    1. Set the Seller Adjustment ID and/or Rma Numbers
    2. New Request (if this is automated, and the marketplace auto-approves the request, no action will need to be taken at ChannelAdvisor)
      1. Seller Reject
      2. Seller Approve and Wait for Product to be Returned
    3. Returned Item
      1. Seller Reject Returned Item
      2. Seller Approve Returned Item for Refund
        1. Once the seller sets this status, the refund will be communicated automatically to the marketplace within 30 minutes

Visual Representation of Workflow

Buyer Initiated Return Endpoints

Order Adjustment Endpoints

POST /v1/OrderAdjustments(id)/ApproveBuyerRequest Approve a buyer-initiated return that is in the NewRma status
POST /v1/OrderAdjustments(id)/RejectBuyerRequest Reject a buyer-initiated return that is in the NewRma status
POST /v1/OrderAdjustments(id)/ApproveReturn Approve a buyer-initiated return that is in the ReadyForReturn status
POST /v1/OrderAdjustments(id)/RejectReturn Reject a buyer-initiated return that is in the ReadyForReturn status
PATCH or PUT /v1/OrderAdjustments(id) Add or Update the RMA Number and Seller Adjustment ID

Item Adjustment Endpoints

POST /v1/OrderItemAdjustments(id)/ApproveBuyerRequest Approve a buyer-initiated return that is in the NewRma status
POST /v1/OrderItemAdjustments(id)/RejectBuyerRequest Reject a buyer-initiated return that is in the NewRma status
POST /v1/OrderItemAdjustments(id)/ApproveReturn Approve a buyer-initiated return that is in the ReadyForReturn status
POST /v1/OrderItemAdjustments(id)/RejectReturn Reject a buyer-initiated return that is in the ReadyForReturn status
PATCH or PUT /v1/OrderItemAdjustments(id) Add or Update the RMA Number and Seller Adjustment ID

Important and/or Required Parameters

Property Type (Max Length) Required Note
OrderAdjustmentID integer (32 bit) Conditional Required for Order-Level Buyer Initiated Return request only. Include in URL.
ChannelAdvisor system generated unique ID for the Order-Level adjustment within this order.
OrderItemAdjustmentID integer (32 bit) Conditional Required for Item-Level Buyer Initiated Return request only. Include in URL.
ChannelAdvisor system generated unique ID for the Item-Level adjustment item within this order.
SellerAdjustmentID string (50) Optional Optional in all scenarios. Include in Body.
Identifier provided by the seller.
RmaNumber string (50) Optional Optional in all scenarios. Include in Body.
RMA Number for Buyer Initiated Returns.

Buyer Initiated Return Request Examples