Amazon External Fulfillment Returns API Use-Case Guide

What is the External Fulfilment Returns API?

The External Fulfilment Returns API enables sellers to list/retrieve returns for Amazon External FulFillment (Seller Flex) channel at a location/merchant level and process them.

Understanding return processing workflow

  1. Retrieve a List of Return Items (listReturns)

    Use Case: Sellers can use this API to retrieve a list of return items based on various filtering criteria.

    Flow:

    1. Determine the filtering criteria, such as returnLocationId, rmaId, status, lastUpdatedAfter, lastUpdatedBefore, maxRe sults (), and nextToken.
    2. Make a GET request to the /externalFulfillment/returns/2021-08- 19/returns endpoint, passing the desired filtering parameters as query parameters.
    3. The response will contain a list of return items that match the specified criteria, along with a nextToken that can be used to fetch the next page of results.

    Query parameters

    Name Description Type Required
    returnLocationId The Amazon External FulFillment ID of the location to which the return was dropped. String No
    rmaId The RMA ID of the return. String No
    status Retrieves only those return items which are in the specified status.
    The most common use-case would be to fetch all new return items which would be in the CREATED status.
    Valid values are
    CREATED,
    CARRIER_NOTIFIED_TO_PICK_UP_FROM_CUSTOMER,
    CARRIER_OUT_FOR_PICK_UP_FROM_CUSTOMER,
    CUSTOMER_CANCELLED_PICK_UP,
    CUSTOMER_RESCHEDULED_PICK_UP,
    PICKED_FROM_CUSTOMER,
    IN_TRANSIT,
    OUT_FOR_DELIVERY,
    DELIVERED     		String No
    reverseTrackingId The reverseTrackingId of the return items to be listed String No
    createdSince Return items whose creation is after the specified date/time are included in the response ISO8601 date/time format No
    createdUntil Return items whose creation is before the specified date/time are included in the response. ISO8601 date/time format No
    lastUpdatedSince The date and time when the return was last updated. ISO8601 date/time format No
    lastUpdatedUntil The date and time when the return was last updated. ISO8601 date/time format No
    maxResults Specify the number of return items to be included in the response. It will default to 10 in case not provided Integer No
    nextToken A cursor representing information about the next page of returns. Use the value returned in previous calls to page through the complete list of returns. String (URL encoded) No

    Header parameters

    Name Description Type Required
    x-amz-access-token The LWA access token for authorizing the request String No

  2. Retrieve a Single Return Item (getReturn)

    Use Case: Sellers can use this API to retrieve information about a single return item.

    Flow:

    1. Obtain the returnId of the return item to be retrieved.
    2. Make a GET request to the /externalFulfillment/returns/2021-08- 19/returns/{returnId} endpoint.

      Path parameters

      Name Description Type Required
      returnId The External FulFillment assigned return id for return item String Yes

      Header parameters

      Name Description Type Required
      x-amz-access-token The LWA access token for authorizing the request String Yes
    3. The response will contain detailed information about the return item, including:
      1. fulfillmentLocationId: The External FulFillment identifier for the location to which the return item had been dropped for delivery.
      2. returnMetadata:
        1. fulfillmentOrderId: The External FulFillment ID of the fulfillment order for which the return was placed.
        2. returnReason: The reason for the item to be returned.
        3. rmaId: The RMA ID of the return.
      3. numberOfUnits: The total number of units in the return.
      4. id: The return item's ID.
      5. lastUpdatedDateTime: The date and time when the return was last updated.
      6. merchantSku: The seller's identifier for the SKU.
      7. marketplaceChannelDetails:
        1. channelSku: The Amazon External FulFillment SKU of the channel.
        2. marketplaceChannel:
          1. marketplaceName: The name of the marketplace.
          2. channelName: The name of the channel within the marketplace.
        3. merchantId: The ID in the marketplace of the merchant or seller to whom the return was dropped.
        4. shipmentId: The marketplace-specific shipment ID.
        5. customerOrderId: The marketplace-specific customer's order ID.
        6. exchangeOrderId: The Amazon External FulFillment ID of the exchange order.
        7. returnLocationId: The Amazon External FulFillment ID of the location to which the return was dropped.
      8. returnType: The type of the return (CUSTOMER or REJECT).
      9. returnShippingInfo:
        1. pickupDateTime: The date and time when the marketplace/channel picked up the return.
        2. forwardTrackingInfo:
        3. carrierName: The name of the courier service used to ship the package.
        4. trackingId: The tracking ID of the forward package
      10. reverseTrackingInfo:
        1. carrierName: The name of the courier service used to ship the package.
        2. trackingId: The tracking ID of the return package
    4. returnLocationId: The External FulFillment identifier for the location to which the return item had been dropped for delivery.
    5. status: The current status of the return.
    6. creationDateTime: The date and time when the return was created in External FulFillment.