The Order Returns API is an optional API that uses the following methods:
orderreturns.list
to determine returned orders.orderreturns.get
to determine an individual returned order.
An order is returned by a customer's request through Google customer service or by using the web application to request a return from the Orders portal.
Regardless of the option used to initiate a return, the Order
assumes the returned
or partiallyReturned
status only if:
- The return is accepted by the merchant.
- A call to
returnlineitem
andrefund
orreturnrefundlineitem
is made.
orderreturns.list
The orderreturns.list
method filters account returns based on optional query parameters, and it returns
a unique orderReturnId
identifier for each Order
returned. This
ReturnId
is used in the get
method to only return results specific to a
particular Order
return.
Example URL for orderreturns.list
method:
GET https://www.googleapis.com/content/v2/{merchantID}/orderreturns
The following is a sample response body for orderreturns.list
with
two orders and their respective returns. Their order IDs
(orderId
) are TEST-4755-72-4132
and TEST-3499-90-3352
respectively:
{
"kind": "content#orderreturnsListResponse",
"resources": [
{
"orderReturnId": "W4JPTRUFONCZEYE",
"orderId": "TEST-4755-72-4132",
"creationDate": "2019-02-07T21:03:50Z",
"returnShipments": [
{
"shipmentId": "WEJPTRUFONCZEYE",
"creationDate": "2019-02-07T21:03:50Z",
"shipmentTrackingInfos": [
{
"carrier": "ups",
"trackingNumber": "idWEJPTRUFONCZEYE"
}
],
"returnMethodType": "byMail"
}
],
"returnItems": [
{
"itemId": "MQYOTRUFONCZEYE",
"returnShipmentIds": [
"WEJPTRUFONCZEYE"
],
"product": {
"id": "online:en:US:d3k3245",
"offerId": "d3k3245",
"targetCountry": "US",
"channel": "online",
"contentLanguage": "en",
"price": {
"value": "70.00",
"currency": "USD"
},
"title": "Cast widget",
"gtin": "00811571013579",
"brand": "Brand A",
"mpn": "H2G2-42",
"condition": "new",
"imageLink": "http://example.com/cast.png"
},
"state": "new",
"customerReturnReason": {
"reasonCode": "changedMind"
}
},
{
"itemId": "MYYOTRUFONCZEYE",
"returnShipmentIds": [
"WEJPTRUFONCZEYE"
],
"product": {
"id": "online:en:US:df4sg53ds9",
"offerId": "df4sg53ds9",
"targetCountry": "US",
"channel": "online",
"contentLanguage": "en",
"price": {
"value": "399.85",
"currency": "USD"
},
"title": "Phone 9",
"gtin": "00821793042684",
"brand": "Brand B",
"mpn": "99HZF001-00",
"condition": "new",
"itemGroupId": "123",
"imageLink": "http://example.com/xus9.png",
"variantAttributes": [
{
"dimension": "color",
"value": "lunar white"
},
{
"dimension": "memory",
"value": "16 GB"
},
{
"dimension": "connectivity",
"value": "Wi-Fi only"
}
]
},
"state": "new",
"customerReturnReason": {
"reasonCode": "changedMind"
}
}
]
},
{
"orderReturnId": "KYYPTRUFONCZEYE",
"orderId": "TEST-3499-90-3352",
"creationDate": "2019-02-07T18:36:35Z",
"returnShipments": [
{
"shipmentId": "KAYPTRUFONCZEYE",
"creationDate": "2019-02-07T18:36:35Z",
"shipmentTrackingInfos": [
{
"carrier": "ups",
"trackingNumber": "idKAYPTRUFONCZEYE"
}
],
"returnMethodType": "byMail"
}
],
"returnItems": [
{
"itemId": "GSGOTRUFONCZEYE",
"returnShipmentIds": [
"KAYPTRUFONCZEYE"
],
"product": {
"id": "online:en:US:d3k3245",
"offerId": "d3k3245",
"targetCountry": "US",
"channel": "online",
"contentLanguage": "en",
"price": {
"value": "70.00",
"currency": "USD"
},
"title": "Cast widget",
"gtin": "00811571013579",
"brand": "Brand A",
"mpn": "H2G2-42",
"condition": "new",
"imageLink": "http://example.com/cast.png"
},
"state": "new",
"customerReturnReason": {
"reasonCode": "changedMind"
}
}
]
}
]
}
orderreturns.get
The orderreturns.get
method gets one order's return based on the returnId
specified. The
orderreturns.list
method
returns a production order's returnId
while the createtestreturn
call on
sandbox returns the returnId
of the return created.
Example URL for orderreturns.get
method:
GET https://www.googleapis.com/content/v2/{merchantID}/orderreturns/{returnId}
The following is a sample response body for orderreturns.get
. This sample has
two return items for orderId: TEST-4755-72-4132
, which was returned in the
orderreturns.list
call above:
{
"orderReturnId": "W4JPTRUFONCZEYE",
"orderId": "TEST-4755-72-4132",
"creationDate": "2019-02-07T21:03:50Z",
"returnShipments": [
{
"shipmentId": "WEJPTRUFONCZEYE",
"creationDate": "2019-02-07T21:03:50Z",
"shipmentTrackingInfos": [
{
"carrier": "ups",
"trackingNumber": "idWEJPTRUFONCZEYE"
}
],
"returnMethodType": "byMail"
}
],
"returnItems": [
{
"itemId": "MQYOTRUFONCZEYE",
"returnShipmentIds": [
"WEJPTRUFONCZEYE"
],
"product": {
"id": "online:en:US:d3k3245",
"offerId": "d3k3245",
"targetCountry": "US",
"channel": "online",
"contentLanguage": "en",
"price": {
"value": "70.00",
"currency": "USD"
},
"title": "Cast widget",
"gtin": "00811571013579",
"brand": "Brand A",
"mpn": "H2G2-42",
"condition": "new",
"imageLink": "http://example.com/cast.png",
"shownImage": "https://encrypted-tbn1.gstatic.com/shopping"
},
"state": "new",
"customerReturnReason": {
"reasonCode": "changedMind"
}
},
{
"itemId": "MYYOTRUFONCZEYE",
"returnShipmentIds": [
"WEJPTRUFONCZEYE"
],
"product": {
"id": "online:en:US:df4sg53ds9",
"offerId": "df4sg53ds9",
"targetCountry": "US",
"channel": "online",
"contentLanguage": "en",
"price": {
"value": "399.85",
"currency": "USD"
},
"title": "Phone 9",
"gtin": "00821793042684",
"brand": "Brand B",
"mpn": "99HZF001-00",
"condition": "new",
"itemGroupId": "123",
"imageLink": "http://example.com/xus9.png",
"shownImage": "https://encrypted-tbn1.gstatic.com/shopping",
"variantAttributes": [
{
"dimension": "color",
"value": "lunar white"
},
{
"dimension": "memory",
"value": "16 GB"
},
{
"dimension": "connectivity",
"value": "Wi-Fi only"
}
]
},
"state": "new",
"customerReturnReason": {
"reasonCode": "changedMind"
}
}
]
}
V2 to V2.1 changes
Though not directly related to the orderreturns
resource, if you are using the returnlineitem
or refund
method to process a return, these two methods are replaced by
the new returnrefundlineitem
method in v2.1.
Testing the Order Returns API
Since testing can be done in either sandbox or production, take care not to inadvertently impact any production orders with your testing. The following are the detailed steps for each environment:
Create a test order.
In production, the Order is automatically created when your customer places an order. However, in sandbox mode, you have to use the createtestorder call or the Merchant Center UI functionality to create a test order.
Orders move from their starting status to
pendingShipment
automatically. However, in sandbox mode, you have to use the advancetestorder call to advance the order to pending shipment state, and you can use APPROVE Action from the Merchant Center Orders tab to perform this step faster.Mark as
Shipped
and thenDelivered
either via the UI or making API callsshiplineitems
andupdateshipment
respectively.Create a test return.
In production, this is initiated by the customer via their Orders portal or via Google customer service. In sandbox, one has to use the
createtestreturn
call. Note that one can get the required request parameterslineItemId
and quantity by making theOrders:get
call for a particularOrder
.Call the
orderreturns:list
orget
methods to get the return details required.