Amazon Smart Connect - Get Returns

Version	Created By	Date	Notes
1.0	Danail Deltchev	11.07.2024	First version
1.1	Danail Deltchev	03.10.2024	Change ShipmentId Mapping in Hemi

Add Mandatory column in the mapping table

The purpose of this page is to specify how Hemi will download Returns from Amazon via the Smart Connect solution to store them and update the orders with all applicable details

Within a shipment in Amazon Smart Connect we can have multiple items with different quantities. Up until the Returns all operations are done for the full Shipment. Getting the Returns though can be (as for any normal marketplace) broken down per item.

The way Amazon Smart Connect operates is that when the buyer places an order they break it down per shipments, then force you as a seller to prepare those shipments (including obtaining labels from them) and then they will come to pick the products up from the your (seller) warehouse.

The Return follows similar steps - if a buyer requests a return this will go through Amazon’s approval steps, wait for the buyer to ship the product (or prepare for pickup) then the product will land in Amazon’s own warehouse and only then it will be rerouted to the your (seller) warehouse

All of these operations are available in the Returns for tracking via different statuses and of course based on the original Shipment there can be multiple returns to one Shipment or one return with multiple products

What we want to do in Hemi is read the returns from Amazon and store them as claims with all their relevant data. And to make a claim as completed we will be looking for the final status of the Amazon Return - DELIVERED. Once received this should make the claim as completed and trigger for a Hemi refund and all values and status updates as per the abstraction

<v1.1>

Please note - as part of the refund creation we need to make sure we are refunding shipping cost for each returned product as well as this is what Amazon are actually doing and if we want to keep accurate accounting info in Hemi we need to replicate. To do this for every Return on Delivered, when we’ve decided a refund needs to be stored, we also need to pass shipping cost to be stored with it and processed through our internal Refund processors.

To calculate the shipping cost we need to take the SKU we are returning (do this for each if more than one product in the Return) and first figure out how much is the shipping cost per quantity. Amazon are providing a shipping cost for the whole order together but they are splitting it per quantity in the order. Example: if we have Order Shipping cost 10 and 2 SKUs in there SKU1111x1qty and SKU2222x4qty in Hemi we should’ve stored shipping cost 2 for SKU1111 and 8 for SKU2222.

Now - if a return comes for SKU2222 for 3 quantity we need to pick the total cost of 8, divide it by the total quantity of 4 to figure out each unit has a shipping cost of 2. At this point we can multiply by the 3 quantity that we are receiving back in the return and pass to the claim/refund processors that we need to store also a refund cost for “6” shipping cost

</v1.1>

<v1.2> We need to have an overlap and manually deduct 10 days before the actual date stored in last_date_run </v1.2>

All validations and checks to be performed as per the standard claims abstraction:

Claims general management

Just as a final note - there are no Acceptance or Rejections on the claims just download from the marketplace with different status until it reaches the final one that triggers everything else

This operation is done via the GET listReturns

Example call:

https://sellingpartnerapi-na.amazon.com/externalFulfillment/returns/2021-08-19/returns?returnLocationId=&rmaId=&status=&lastUpdatedAfter=&lastUpdatedBefore=&maxResults=&nextToken=

Usable Parameters:

Parameter Name	Parameter Description	Type	Required	Hemi Notes
returnLocationId	The SmartConnect location identifier for which return items are to be retrieved	String	No	Might be added in the future with a field in account Amazon
rmaId	The RMA id of the return items to be listed	String	No	N/A
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
lastUpdatedAfter	Return items whose creation is after the specified date/time are included in the response. This field should be in the ISO8601 date/time format.	Date	No	Use for filtering results with Hemi Last Date Run
lastUpdatedBefore	Return items whose creation is before the specified date/time are included in the response. This field should be in the ISO8601 date/time format.	Date	No	N/A
maxResults	Specify the number of return items to be included in the response. It will default to 10 in case not provided.	Int (32)	No	Up to devs 🙂
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	No	Please use it 😀

Example response:

Amazon Smart Connect Returns Download Map.xlsx

Amazon fields				Hemi Mapping	<v1.1>Hemi Mandatory</v1.1>	Hemi Notes
returns
	id			Order Claim > Marketplace ID	y
	returnLocationId			N/A
	merchantSku			Order Claim Row > Order Item Line ID	y	We need to map the "merchantSku" to the Product in Order > SKU and then based on the "numberOfUnits" below in the payload decide how many lines we are adding in Order Claim Row
	returnType			Order Claim > Initiated By		Amazon provides two options which we should map the following way to ours:`CUSTOMER` = Buyer`REJECT` = Marketplace
	numberOfUnits				y	See note on "merchantSku" above
	status			Order Claim > Marketplace Status	y
	fulfillmentLocationId			N/A
	creationDateTime			Order Claim > Marketplace Date	y
	lastUpdatedDateTime			N/A
	returnMetadata
		returnReason		Order Claim > Marketplace Reason
		rmaId		N/A
		fulfillmentOrderId		N/A
		invoiceInformation
			id	N/A
	returnShippingInfo
		deliveryDateTime		Order Claim Shipping Info > Delivery by date
		pickupDateTime		Order Claim Shipping Info > Ship by date
		forwardTrackingInfo
			carrierName	N/A
			trackingId	N/A
		reverseTrackingInfo
			carrierName	Order Claim Shipping Info > Courier
			trackingId	Order Claim Shipping Info > Tracking number
	marketplaceChannelDetails
		marketplaceChannel
			marketplaceName	N/A
			channelName	N/A
		merchantId		N/A
		shipmentId			y	<v1.1>

Use this field + customerOrderId to map to which order in Hemi we are storing the return. Map this to Orders > Marketplace Order ID from Hemi

The format is shipmentId_customerOrderId </v1.1> | | | | customerOrderId | | N/A | | <v1.1> Use shipmentId+ this field to map to which order in Hemi we are storing the return. Map this to Orders > Marketplace Order ID from Hemi

<v1.1>

Please note - everything that is not marked as Mandatory if missing should be skipped and should not break our download and store of the claim

</v.1.1>

The whole operation should look like this - As we are downloading all returns we want to keep the “Order Claim > Claim Status” as “Created” until the moment we reach the “DELIVERED” Amazon status (mapped from the returns.status node from the Amazon Returns payload). Once we do so we want the Hemi “Claim Status” to become “Accepted & Refunded” and we want to trigger the Refund creation process in Hemi for said claim

Marketplaces / Amazon SP API - Technical Scope / Amazon Smart Connect / Amazon Smart Connect - Get Returns

Amazon Smart Connect - Get Returns