eBay Get Return Tracking Info
Use this call to retrieve information on a specific return request. The user can retrieve either the full details or a summary of the return. In our case we will be always getting the FULL details. eBay documentation available here - https://developer.ebay.com/Devzone/post-order/post-order_v2_return-returnid__get.html#Response.detail.replacementShipmentInfo.shipmentTracking.destinationAddress
This request is part of the POST ORDER API thus we will need to use the new tokens placed in account eBay.
Request:
GET https://api.ebay.com/post-order/v2/return/{returnId}?fieldgroups={FULL}URI parameters
| Parameter | Hemi Field | Type | Required? | Comment |
|---|---|---|---|---|
| returnId | Order Claim > Marketplace ID | string | Required | The unique eBay-assigned ID of the return. The returnId value is required to identify the return for which shipment tracking activity is being retrieved. |
| fieldgroups | string | Required | Hardcoded as “FULL“ |
| Header | Hemi Field | Type | Required? | Comment |
|---|---|---|---|---|
| Accept | string | Optional | Hardcode one of these application/json or application/xml | |
| Authorization | account eBay > Access Token | TOKEN {{Access Token}} | Required | instead of BEARER we need to use TOKEN |
| X-EBAY-C-MARKETPLACE-ID | string | Required | Based on the eBay marketplace we will need to use on of these | |
EBAY_US, EBAY_UK, EBAY_DE, EBAY_AU, and EBAY_CA |
From the whole response the only bit we will need is the detail > returnShipmentInfo >shipmentTracking
FULL RESPONSE
{
"summary":{
"returnId":"5193000550",
"orderId":"10-07558-05992",
"buyerLoginName":"tyrgab-23",
"sellerLoginName":"currys",
"currentType":"MONEY_BACK",
"state":"CLOSED",
"status":"ESCALATED",
"creationInfo":{
"item":{
"itemId":"114853316170",
"transactionId":"2231031350001",
"returnQuantity":1,
"itemTitle":"NINTENDO Switch - Neon Red & Blue - Currys"
},
"type":"MONEY_BACK",
"reason":"MISSING_PARTS",
"reasonType":"SNAD",
"comments":{
"content":"Missing controllers, "
},
"creationDate":{
"value":"2021-09-07T10:52:32.000Z"
}
},
"sellerTotalRefund":{
"estimatedRefundAmount":{
"value":279.0,
"currency":"GBP"
}
},
"buyerTotalRefund":{
"estimatedRefundAmount":{
"value":279.0,
"currency":"GBP"
}
},
"sellerResponseDue":{
"activityDue":"SELLER_ISSUE_REFUND",
"respondByDate":{
"value":"2021-09-29T22:59:59.000Z"
}
},
"buyerResponseDue":{
"activityDue":"BUYER_ESCALATE",
"respondByDate":{
"value":"2021-10-14T22:59:59.000Z"
}
},
"escalationInfo":{
"caseId":"5278987256",
"buyerEscalationEligibilityInfo":{
"startTime":null,
"endTime":null,
"eligible":false
},
"sellerEscalationEligibilityInfo":{
"startTime":null,
"endTime":null,
"eligible":false
},
"caseType":"SNAD"
},
"sellerAvailableOptions":[
{
"actionType":"OTHER",
"actionURL":"https://www.ebay.co.uk/rtn/Return/ReturnsDetail?returnId=5193000550"
}
],
"buyerAvailableOptions":[
{
"actionType":"BUYER_PRINT_SHIPPING_LABEL",
"actionURL":"https://www.ebay.co.uk/rtn/Return/ReturnsDetail?returnId=5193000550"
},
{
"actionType":"EXTERNAL_CLAIM_OPENED",
"actionURL":"https://www.ebay.co.uk/rtn/Return/ReturnsDetail?returnId=5193000550"
}
],
"returnPolicy":{
"multipleReturnAddresses":false,
"rmarequired":false
},
"flags":{
"postTransactionRtn":true,
"isGST":false,
"faultyReturnNoeMBGProtection":false,
"returnViaPsaAuthPartner":false,
"isGSP":false,
"eBPnonPaypal":true,
"enableCalendarDays":true,
"request4Return":true,
"isTaxPartnerFee":false,
"lessThanAFullRefundAvailable":false,
"trackingUploaded":true,
"businessDaysAfterSmir":true,
"isFasterResAutoCloseEligible":true,
"purchaseLabelAvailable":false,
"multipleReturnAddress":false,
"lessThanAFullRefundIssued":false,
"eligibleForReplacement":false,
"handlingTaxOnly":false,
"shippingLabelPrinted":false,
"withinReturnWindow":true,
"createdFromNewReturnsFlow":true,
"isSellerProvideOwnLabel":true,
"calendarDaysBeforeSmir":false,
"isEbayPlusTxn":false,
"isRefundDeductionApplied":false,
"isReturnCarrierConfirmed":false,
"handlingCostOnly":false,
"canSellerDeclineReturn":false,
"sellerStartFromNewRtnExp":true,
"requestLabel4Return":false,
"isServiceFeeExcludedFromRefund":false,
"cuidEnabled":true,
"autoRouteRuleTriggered":false,
"autoApprovalEbayPlus":false,
"feeNettingRefundFlow":true,
"goToNewReturnExp":true,
"markAsShipped":true,
"isGAP":false,
"buyerShipmentDue":false,
"rmaRequired":false,
"proxySNAD":false,
"canSellerUploadLabel":true,
"isGeo":false,
"auEbayPlusAutoApproval":false,
"isExchange":false,
"thirdPartyLabelAvailable":false,
"eligibleForLabelChargeDeduction":false,
"paypalGuest":false,
"autoApprovalRemorse":false,
"lvtImmediateRefund":false,
"ebayPromotedLabel":false,
"autoApprovalPsa":false,
"holidayReturn":false,
"isPSA":false,
"autoRefundTriggered":false,
"sendMessageAvailable":true,
"isFaultyReturnMandateTracking":false,
"isLegacyTaxEngine":false,
"businessDaysBeforeSmir":true,
"replacementNoShipBack":false,
"autoApprovalRuleTriggered":false,
"enterpriseReturn":false,
"isInvoiceToSeller":false,
"isExternalClaimOpened":false,
"escalateAvableForSeller":true,
"iseBayGarantee":false,
"isVAT":false,
"smirEnded":false,
"isPartialRefunded":false,
"isGAPSellerFault":false,
"sellerInNewRtnExp":true,
"isRefundDeductionAvailable":false,
"calendarDaysAfterSmir":false,
"shouldCallCops":true,
"isFasterResAutoApproveAndOrLabelEligible":true,
"isStateTax":false,
"isDownloadLabelAvailable":false,
"escalateAvableForBuyer":true,
"isFeeNettedOrder":true,
"deliveryStatusConfirmed":true,
"autoApprovalSnad":false,
"canSellerReportBuyer":true,
"isFasterResAutoLabelEligible":true,
"gpltLabelFlow":false,
"eligibleForImprovedRefundFailure":false,
"lvtSubsidizedLabel":false,
"isEbayIntermediated":true,
"partialRefundFromNonPayPal":false,
"shippingLabelAvailable":true,
"replacementLabelPrinted":false,
"hasSellerReportedBuyer":false,
"triggerByDispositionRule":false
},
"timeoutDate":{
"value":"2021-10-11T22:59:59.999Z"
},
"isSellerProtected":false
},
"detail":{
"marketplaceId":"EBAY_GB",
"itemDetail":{
"itemId":"114853316170",
"transactionId":"2231031350001",
"listingSiteId":3,
"returnQuantity":1,
"itemTitle":"NINTENDO Switch - Neon Red & Blue - Currys",
"itemPicUrl":"https://i.ebayimg.com/00/s/ODg3WDEwMDA=/z/wTMAAOSwp5Fgyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/yQQAAOSwNMZgyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/cEYAAOSwzRxgyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/hfoAAOSwH51gyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/b6EAAOSwuhRgyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/qCoAAOSwPN5gyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/al0AAOSwtBlgyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/uswAAOSwbuZgyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/-XIAAOSwUJtgyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/iq8AAOSwSFhgyfkk/$_1.JPG?set_id=880000500F;https://i.ebayimg.com/00/s/NTMyWDYwMA==/z/kE4AAOSw3~lgyfkk/$_1.JPG?set_id=880000500F",
"transactionDate":{
"value":"2021-09-03T19:57:56.000Z"
},
"itemPrice":{
"value":279.0,
"currency":"GBP"
},
"ebayPlusTxn":false
},
"buyerLoginName":"tyrgab-23",
"sellerLoginName":"currys",
"buyerEmailAddress":"tyronne.gabriel@gmail.com",
"sellerEmailAddress":"ebay@currys.co.uk",
"checkoutType":"ONLINE",
"responseHistory":[
{
"author":"BUYER",
"activity":"BUYER_CREATE_RETURN",
"fromState":"INITIAL",
"toState":"RETURN_REQUESTED",
"creationDate":{
"value":"2021-09-07T10:52:32.000Z"
},
"notes":"Missing controllers, ",
"attributes":{
"sellerReturnAddress":{
"name":"Dixons Carphone eBay Department",
"address":{
"addressLine1":"Main Office",
"addressLine2":"Building Two, Long Hollow Way",
"city":"Newark",
"stateOrProvince":"Nottinghamshire",
"postalCode":"NG24 2NH",
"country":"GB"
}
}
}
},
{
"author":"SYSTEM",
"activity":"REMINDER_SELLER_TO_RESPOND",
"fromState":"RETURN_REQUESTED",
"toState":"RETURN_REQUESTED",
"creationDate":{
"value":"2021-09-08T23:10:51.000Z"
},
"attributes":{
}
},
{
"author":"SELLER",
"activity":"SELLER_APPROVE_REQUEST",
"fromState":"RETURN_REQUESTED",
"toState":"RETURN_LABEL_PENDING",
"creationDate":{
"value":"2021-09-10T08:12:18.000Z"
},
"attributes":{
}
},
{
"author":"SELLER",
"activity":"SELLER_PROVIDE_LABEL",
"fromState":"RETURN_LABEL_PENDING",
"toState":"ITEM_READY_TO_SHIP",
"creationDate":{
"value":"2021-09-10T08:13:06.000Z"
},
"notes":"Thank you for your message. Please contact Team KnowHow via 0344 561 1234. They will be able to provide you with a returns label. Kind regards, Julia Currys PC World eBay store",
"attributes":{
"updatedCarrier":"Royal Mail"
}
},
{
"author":"SYSTEM",
"activity":"REMINDER_FOR_SHIPPING",
"fromState":"ITEM_READY_TO_SHIP",
"toState":"ITEM_READY_TO_SHIP",
"creationDate":{
"value":"2021-09-21T23:04:38.000Z"
},
"attributes":{
}
},
{
"author":"BUYER",
"activity":"BUYER_PROVIDE_TRACKING_INFO",
"fromState":"ITEM_READY_TO_SHIP",
"toState":"ITEM_SHIPPED",
"creationDate":{
"value":"2021-09-23T19:09:45.000Z"
},
"attributes":{
"updatedTrackingNumber":"ny487203359gb",
"updatedCarrier":"Royal Mail"
}
},
{
"author":"SYSTEM",
"activity":"NOTIFIED_DELIVERED",
"fromState":"ITEM_SHIPPED",
"toState":"ITEM_DELIVERED",
"creationDate":{
"value":"2021-09-27T20:05:19.000Z"
},
"attributes":{
"updatedTrackingNumber":"ny487203359gb",
"updatedCarrier":"Royal Mail"
}
},
{
"author":"SYSTEM",
"activity":"REMINDER_FOR_REFUND",
"fromState":"ITEM_DELIVERED",
"toState":"ITEM_DELIVERED",
"creationDate":{
"value":"2021-09-27T23:06:21.000Z"
},
"attributes":{
}
},
{
"author":"SYSTEM",
"activity":"REMINDER_FOR_REFUND",
"fromState":"ITEM_DELIVERED",
"toState":"ITEM_DELIVERED",
"creationDate":{
"value":"2021-09-28T23:08:49.000Z"
},
"attributes":{
}
},
{
"author":"SYSTEM",
"activity":"TIME_OUT_FOR_REFUND",
"fromState":"ITEM_DELIVERED",
"toState":"REFUND_TIMEOUT",
"creationDate":{
"value":"2021-09-29T23:09:52.000Z"
},
"attributes":{
}
},
{
"author":"BUYER",
"activity":"BUYER_ESCALATE",
"fromState":"REFUND_TIMEOUT",
"toState":"CLOSED",
"creationDate":{
"value":"2021-09-29T23:28:42.000Z"
},
"notes":"I still haven’t been refunded ",
"attributes":{
"escalateReason":"NO_REFUND_RECEIVED"
}
}
],
"refundInfo":{
"estimatedRefundDetail":{
"itemizedRefundDetails":[
{
"refundFeeType":"PURCHASE_PRICE",
"estimatedAmount":{
"value":279.0,
"currency":"GBP"
},
"overwritableBySeller":false,
"amountEditable":false
}
],
"optionalRefundLineItems":[
],
"isRtnShippingEditable":false
}
},
"buyerAddress":{
"name":"Tyronne Gabriel",
"address":{
"addressLine1":"42 Ninian Road",
"city":"Hemel Hempstead",
"stateOrProvince":"Hertfordshire",
"postalCode":"HP2 6NA",
"country":"GB"
}
},
"sellerAddress":{
"name":"Dixons Carphone eBay Department",
"address":{
"addressLine1":"Main Office",
"addressLine2":"Building Two, Long Hollow Way",
"city":"Newark",
"stateOrProvince":"Nottinghamshire",
"postalCode":"NG24 2NH",
"country":"GB"
}
},
"returnShipmentInfo":{
"shipmentTracking":{
"shippingMethod":"SELF_MAIL",
"shippedBy":"BUYER",
"trackingNumber":"ny487203359gb",
"carrierId":10,
"carrierEnum":"ROYAL_MAIL",
"carrierName":"Royal Mail",
"carrierUsed":"Royal Mail",
"deliveryStatus":"DELIVERED",
"shipDate":{
"value":"2021-09-23T19:09:45.000Z"
},
"actualDeliveryDate":{
"value":"2021-09-27T20:05:19.000Z"
},
"markAsReceived":false,
"active":true,
"labelPrintExpired":false,
"labelVoidExpired":false,
"labelDate":{
"value":"2021-09-10T08:13:06.000Z"
},
"labelAvailableUntilDate":"Sep 13, 2021",
"multipleCarrierAvailable":false
},
"shippingLabelCost":{
"totalAmount":{
"value":3.35,
"currency":"GBP"
},
"itemizedReturnShippingCost":[
{
"returnShippingCostType":"LABEL_COST",
"amount":{
"value":3.35,
"currency":"GBP"
}
}
]
},
"payee":"SELLER",
"allShipmentTrackings":[
{
"shippingMethod":"SELF_MAIL",
"shippedBy":"BUYER",
"trackingNumber":"ny487203359gb",
"carrierId":10,
"carrierEnum":"ROYAL_MAIL",
"carrierName":"Royal Mail",
"carrierUsed":"Royal Mail",
"deliveryStatus":"DELIVERED",
"shipDate":{
"value":"2021-09-23T19:09:45.000Z"
},
"actualDeliveryDate":{
"value":"2021-09-27T20:05:19.000Z"
},
"markAsReceived":false,
"active":true,
"labelPrintExpired":false,
"labelVoidExpired":false,
"labelDate":{
"value":"2021-09-10T08:13:06.000Z"
},
"labelAvailableUntilDate":"Sep 13, 2021",
"multipleCarrierAvailable":false
},
{
"shippingMethod":"SHIPPING_LABEL",
"shippedBy":"BUYER",
"carrierId":10,
"carrierEnum":"ROYAL_MAIL",
"carrierName":"Royal Mail",
"carrierUsed":"Royal Mail",
"deliveryStatus":"UNKNOWN",
"destinationAddress":{
"name":"Dixons Carphone eBay Department",
"address":{
"addressLine1":"Main Office",
"addressLine2":"Building Two, Long Hollow Way",
"city":"Newark",
"stateOrProvince":"Nottinghamshire",
"postalCode":"NG24 2NH",
"country":"GB"
}
},
"originAddress":{
"name":"Tyronne Gabriel",
"address":{
"addressLine1":"42 Ninian Road",
"city":"Hemel Hempstead",
"stateOrProvince":"Hertfordshire",
"postalCode":"HP2 6NA",
"country":"GB"
}
},
"markAsReceived":false,
"active":false,
"labelPrintExpired":false,
"labelVoidExpired":false,
"multipleCarrierAvailable":false
}
]
},
"closeInfo":{
"returnCloseReason":"ESCALATED",
"buyerCloseReason":"UNKNOWN",
"returnCloseDate":{
"value":"2021-09-29T23:28:42.000Z"
}
}
}
}Please have in mind due to the size of the example request and what we need bellow you will find mapping only for the fields we need. Everything else is to be treated as "N/A"
| eBay Filed | Hemi Field | Comment | ||||
|---|---|---|---|---|---|---|
| detail | ||||||
| returnShipmentInfo | ||||||
| ShipmentTracking | N/A | |||||
| shipmentId | N/A | Not always available | ||||
| shippingMethod | Order Claim Shipping Info > Type | |||||
| shippedBy | N/A | |||||
| trackingNumber | Order Claim Shipping Info > Tracking Number | Not always available | ||||
| New field | ||||||
| carrierId | N/A | |||||
| carrierEnum | N/A | |||||
| carrierName | Order Claim Shipping Info > Courier | |||||
| carrierUsed | N/A | |||||
| deliveryStatus | Order Claim Shipping Info >Marketplace Status | New Field | ||||
| destinationAddress | Not always available | |||||
| name | Order Claim Shipping Info > Name | |||||
| address | ||||||
| addressLine1 | Order Claim Shipping Info >Address 1 | |||||
| addressLine2 | Order Claim Shipping Info >Address2 | |||||
| city | Order Claim Shipping Info >City | |||||
| stateOrProvince | Order Claim Shipping Info >State | New Field | ||||
| postalCode | Order Claim Shipping Info >Postal Code | |||||
| country | Order Claim Shipping Info >Country Code | |||||
| Order Claim Shipping Info >Country Name | Based on the country code we add the country name | |||||
| originAddress | Not always available | |||||
| name | N/A | |||||
| address | ||||||
| addressLine1 | N/A | |||||
| addressLine2 | N/A | |||||
| city | N/A | |||||
| stateOrProvince | N/A | |||||
| postalCode | N/A | |||||
| country | N/A | |||||
| actualShipDate | This field is not returned until the order line item has been marked as in transit. | |||||
| New field | ||||||
| value | Order Claim Shipping Info > Ship Date | |||||
| actualDeliveryDate | This field is not returned until the order line item has been marked as delivered. | |||||
| New Field | ||||||
| value | Order Claim Shipping Info > Delivery Date | |||||
| markAsReceived | N/A | |||||
| active | N/A | |||||
| labelPrintExpired | N/A | |||||
| labelVoidExpired | N/A | |||||
| labelDate | ||||||
| value | N/A | |||||
| labelAvailableUntilDate | N/A | |||||
| multipleCarrierAvailable | N/A | |||||
| Order Claim Shipping Info > Error | If we receive any error we store it here | |||||
| New field | ||||||
| Order Claim Shipping Info > Status | Internal Status field for future use | |||||
| New field |
Because there are status which are not final we will need to get and update the actual return information for example if we have a return with status CREATED we call the return id again then we will receive a status IN_TRANSIT and we call the return id again until we get CANCELLED or DELIVERED
MARKETPLACE STATUS MAPPING
| eBay Status | Comment | Action |
|---|---|---|
| CANCELLED | Indicates the current shipment tracking information has been canceled. | Final status do not get the return again |
| CREATED | Indicates shipment tracking has been initiated. | Initial status we will get the return again |
| DELIVERED | Indicates the item was delivered according to the shipment tracking history. | Final status do not get the return again |
| IN_TRANSIT | Indicates the item is in-transit to the recipient according to the shipment tracking history. | Initial status we will get the return again |
| UNKNOWN | Indicates shipment tracking status of the item is unknown. | Final status do not get the return again |
The idea behind this is we are receiving different set of information depends on the status on the return thus during the transition of the statuses we will need to update the missing fields. For example actualDeliveryDate is received only when we have status DELIVERED.
INTERNAL STATUS MAPPING
| eBay Status | Comment | Action |
|---|---|---|
| Pending | Initial status set as default | |
| Error | If we receive an error in the response | |
| In Progress | If we receive IN_TRANSIT, CREATED Marketplace Status | |
| Completed | If we receive DELIVERED, CANCELLED, UNKNOWN Marketplace Status |
Error Handling:
eBay does not provide any.
Suggested Cron Run Time:
Every hour.
Precautions:
Because there are no filters from which date to start by default we would like to start getting the return details for the last 30 days and from then on to filter them by the return status which we will receive. However if we receive any error and we are not storing them we will get in a loop and call the same return id within these 30days. Thus we will need to filter and get all returns in the last 30days with Order Claim Shipping Info > Status = “Pending“