Overview
You can use the following orderreturns
resource v2.1
methods to manage your returns:
orderreturns.list
to see a list of your returns.orderreturns.get
to see a specific return.orderreturns.acknowledge
to acknowledge a return.orderreturns.createorderreturn
to create a new return.orderreturns.labels.create
to upload a return label.orderreturns.process
to process or reject a return.
Here's a summary of the returns process:
Here are explanations of the orderreturns
methods:
Methods
orderreturns
includes the following methods:
orderreturns.list
You can use orderreturns.list
to view returns based on
optional query parameters.
This method provides a unique orderReturnId
for each Order
. You can use this
orderReturnId
as the returnId
to call the get
method.
Here's a sample URL:
GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns
Here's a sample sandbox URL:
GET https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns
Here's a sample response from orderreturns.list
with two order returns. Their
orderId
s are TEST-8984-80-0722
and TEST-4329-83-8262
.
{
"kind": "content#orderreturnsListResponse",
"resources": [
{
"orderReturnId": "LSYJTDCD7NCZEYE",
"orderId": "TEST-8984-80-0722",
"creationDate": "2020-02-11T17:24:13Z",
"returnShipments": [
{
"shipmentId": "LSYJTDCD7NCZEYE",
"state": "new",
"creationDate": "2020-02-11T17:24:13Z",
"shipmentTrackingInfos": [
{
"carrier": "deliv",
"trackingNumber": "tracking_number_idLSYJTDCD7NCZEYE"
}
],
"returnMethodType": "byMail"
}
],
"returnItems": [
{
"itemId": "LKGJTDCD7NCZEYE",
"returnItemId": "L2ZJTDCD7NCZEYE",
"returnShipmentIds": [
"LSYJTDCD7NCZEYE"
],
"product": {
"id": "online:en:US:156d6ab2-ed9d-4009-8d01-93cf9a62f54f",
"offerId": "156d6ab2-ed9d-4009-8d01-93cf9a62f54f",
"targetCountry": "US",
"contentLanguage": "en",
"price": {
"value": "70.00",
"currency": "USD"
},
"title": "Google Chromecast",
"gtin": "00811571013579",
"brand": "Google",
"mpn": "H2G2-42",
"condition": "new",
"imageLink": "http://www.gstatic.com/shopping-content-api/product_images/chromecast.jpg",
"shownImage": "https://encrypted-tbn1.gstatic.com/shopping?q=tbn:ANd9GcQnZBrlSh95-rICAk"
},
"state": "new",
"customerReturnReason": {
"reasonCode": "changedMind"
},
"refundableAmount": {
"priceAmount": {
"value": "70.00",
"currency": "USD"
},
"taxAmount": {
"value": "0.00",
"currency": "USD"
}
}
}
],
"returnPricingInfo": {
"refundableItemsTotalAmount": {
"priceAmount": {
"value": "70.00",
"currency": "USD"
},
"taxAmount": {
"value": "0.00",
"currency": "USD"
}
},
"refundableShippingAmount": {
"priceAmount": {
"value": "20.00",
"currency": "USD"
},
"taxAmount": {
"value": "0.00",
"currency": "USD"
}
}
}
},
{
"orderReturnId": "L2GJTDCD7NCZEYE",
"orderId": "TEST-4329-83-8262",
"creationDate": "2020-02-11T17:24:11Z",
"returnShipments": [
{
"shipmentId": "L2GJTDCD7NCZEYE",
"state": "new",
"creationDate": "2020-02-11T17:24:11Z",
"shipmentTrackingInfos": [
{
"carrier": "deliv",
"trackingNumber": "tracking_number_idL2GJTDCD7NCZEYE"
}
],
"returnMethodType": "byMail"
}
],
"returnItems": [
{
"itemId": "LSHJTDCD7NCZEYE",
"returnItemId": "LCHJTDCD7NCZEYE",
"returnShipmentIds": [
"L2GJTDCD7NCZEYE"
],
"product": {
"id": "online:en:US:f37b9d95-fbc5-46be-ad63-c49fbf1f29b2",
"offerId": "f37b9d95-fbc5-46be-ad63-c49fbf1f29b2",
"targetCountry": "US",
"contentLanguage": "en",
"price": {
"value": "70.00",
"currency": "USD"
},
"title": "Google Chromecast",
"gtin": "00811571013579",
"brand": "Google",
"mpn": "H2G2-42",
"condition": "new",
"imageLink": "http://www.gstatic.com/shopping-content-api/product_images/chromecast.jpg",
"shownImage": "https://encrypted-tbn1.gstatic.com/shopping?q=tbn:ANd9GcQnZBrlc&usqp=CAk"
},
"state": "new",
"customerReturnReason": {
"reasonCode": "changedMind"
},
"refundableAmount": {
"priceAmount": {
"value": "70.00",
"currency": "USD"
},
"taxAmount": {
"value": "0.00",
"currency": "USD"
}
}
}
],
"returnPricingInfo": {
"refundableItemsTotalAmount": {
"priceAmount": {
"value": "70.00",
"currency": "USD"
},
"taxAmount": {
"value": "0.00",
"currency": "USD"
}
},
"refundableShippingAmount": {
"priceAmount": {
"value": "20.00",
"currency": "USD"
},
"taxAmount": {
"value": "0.00",
"currency": "USD"
}
}
}
}
]
}
orderreturns.get
You can use orderreturns.get
to view an individual return based on the returnId
. To find the
returnId
, use the orderreturns.list
method to discover a production
order's orderReturnId
, or save the returned returnId
when creating a test
return with the createtestreturn
sandbox call.
Here's a sample URL:
GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/returnId
Here's a sample sandbox URL:
GET https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/returnId
Here's a sample response. This sample has two return items for
orderId: TEST-8984-80-0722
, which was returned in the orderreturns.list
call above.
{
"kind": "content#orderreturnsGetResponse",
"resources":
{
"orderReturnId": "LSYJTDCD7NCZEYE",
"orderId": "TEST-8984-80-0722",
"creationDate": "2020-02-11T17:24:13Z",
"returnShipments": [
{
"shipmentId": "LSYJTDCD7NCZEYE",
"state": "new",
"creationDate": "2020-02-11T17:24:13Z",
"shipmentTrackingInfos": [
{
"carrier": "deliv",
"trackingNumber": "tracking_number_idLSYJTDCD7NCZEYE"
}
],
"returnMethodType": "byMail"
}
],
"returnItems": [
{
"itemId": "LKGJTDCD7NCZEYE",
"returnItemId": "L2ZJTDCD7NCZEYE",
"returnShipmentIds": [
"LSYJTDCD7NCZEYE"
],
"product": {
"id": "online:en:US:156d6ab2-ed9d-4009-8d01-93cf9a62f54f",
"offerId": "156d6ab2-ed9d-4009-8d01-93cf9a62f54f",
"targetCountry": "US",
"contentLanguage": "en",
"price": {
"value": "70.00",
"currency": "USD"
},
"title": "Google Chromecast",
"gtin": "00811571013579",
"brand": "Google",
"mpn": "H2G2-42",
"condition": "new",
"imageLink": "http://www.gstatic.com/shopping-content-api/product_images/chromecast.jpg",
"shownImage": "https://encrypted-tbn1.gstatic.com/shopping?q=tbnZ6ibvjDsPWzlmO&usqp=CAk"
},
"state": "new",
"customerReturnReason": {
"reasonCode": "changedMind"
},
"refundableAmount": {
"priceAmount": {
"value": "70.00",
"currency": "USD"
},
"taxAmount": {
"value": "0.00",
"currency": "USD"
}
}
}
],
"returnPricingInfo": {
"refundableItemsTotalAmount": {
"priceAmount": {
"value": "70.00",
"currency": "USD"
},
"taxAmount": {
"value": "0.00",
"currency": "USD"
}
},
"refundableShippingAmount": {
"priceAmount": {
"value": "20.00",
"currency": "USD"
},
"taxAmount": {
"value": "0.00",
"currency": "USD"
}
}
}
}
}
orderreturns.acknowledge
You can use
orderreturns.acknowledge
to acknowledge a return and set the status of acknowledged
as True
.
You can then call orderreturns.list
to see a list of newest returns
filtered by ack
parameter.
Here's a sample URL:
POST
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/returnId/acknowledge
Here's a sample sandbox URL:
POST
https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/returnId/acknowledge
Here's a sample request:
{
"operationId": "ack_op_1"
}
Here's a sample response:
{
"kind": "content#orderreturnsAcknowledgeResponse",
"executionStatus": "executed"
}
orderreturns.createorderreturn
You can use
orderreturns.createorderreturn
,
and to create a new return. You can set returnShipmentType
to one of the
following:
inStore
: For items returned in store.byMail
: For items returned by mail.
Here's a sample URL:
POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/createorderreturn
Here's a sample sandbox URL:
POST https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/createorderreturn
Here's a sample request:
{
"orderId": "TEST-8984-80-0722",
"operationId": "operation-uuid-1234",
"returnMethodType": "inStore",
"lineItems": [
{
"lineItemId": "LKGJTDCD7NCZEYE",
"quantity": 3
}
],
}
Here's a sample response:
{
"kind": "content#orderreturnsCreateorderreturnResponse",
"executionStatus": "executed",
"merchantOrderReturn": Object([MerchantOrderReturn](/shopping-content/reference/rest/v2.1/MerchantOrderReturn))
}
orderreturns.process
You can use orderreturns.process
to
reject or process a return.
The paymentType
field of orderreturns.process
can be one of the following:
originalFop
: Refund to the original form of payment.cash
: Refund in cash.credit
: Refund in store credit.
Full refunds
You can issue full refunds to the original form of payment by setting the
paymentType
to originalFop
. If you want to refund the order to a different
form of payment than the original, you must use partialRefund
.
See the In-store returns section for more information.
Here's an example of a full refund due to customer cancellation:
"returnRefundReason": "customerCanceled"
.
Here's a sample URL:
POST
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/returnId/process
Here's a sample sandbox URL:
POST
https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/returnId/process
Here's a sample request:
{
"operationId": "process_op_1",
"refundShippingFee": {
"fullRefund": true,
"reasonText": "canceled",
"returnRefundReason": "customerCanceled"
},
"returnItems": [
{
"refund": {
"fullRefund": true,
"reasonText": "canceled",
"returnRefundReason": "customerCanceled"
},
"returnItemId": "LCFJTDCD7NCZEYE"
}
]
}
Here's a sample response:
{
"kind": "content#orderreturnsProcessResponse",
"executionStatus": "executed"
}
Partial refunds
You can use partial refunds to refund a specific amount, and to issue a full refund to a form of payment that's different from the original form of payment for the order.
Here's a sample request for a partial refund due to customer cancellation:
{
"operationId": "process_op_1",
"refundShippingFee": {
"fullRefund": true,
"reasonText": "canceled",
"returnRefundReason": "customerCanceled"
},
"returnItems": [
{
"refund": {
"partialRefund": {
"priceAmount": {
"currency": "USD",
"value": "20"
},
"taxAmount": {
"currency": "USD",
"value": "0"
}
},
"reasonText": "canceled",
"returnRefundReason": "customerCanceled"
},
"returnItemId": "LCFJTDCD7NCZEYE"
}
]
}
Here's a sample response:
{
"kind": "content#orderreturnsProcessResponse",
"executionStatus": "executed"
}
In-store returns
If you have physical store locations, your customers can initiate a return in-store and receive refunds in the following forms:
- Original form of payment
- Cash
- Store credit
To process an in-store return, find the return in your account with the orderId
and orderreturns.list
. If you don't see the return under your account, create
a new return with orderreturns.createorderreturn
and set the returnMethodType
to inStore
.
You can check the refundable amount of each line item in the MerchantOrderReturn
object.
The following example shows how to refund a customer in cash:
Here's a sample URL:
POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/returnId/process
Here's a sample sandbox URL:
POST https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/returnId/process
Here's a sample request:
{
"operationId": "process_op_1",
"refundShippingFee": {
"paymentType": "cash",
"partialRefund": {
"priceAmount": {
"currency": "USD",
"value": "5.99"
},
"taxAmount": {
"currency": "USD",
"value": "0"
}
},
"reasonText": "canceled",
"returnRefundReason": "customerCanceled"
},
"returnItems": [
{
"refund": {
"paymentType": "cash",
"partialRefund": {
"priceAmount": {
"currency": "USD",
"value": "20"
},
"taxAmount": {
"currency": "USD",
"value": "0"
}
},
"reasonText": "canceled",
"returnRefundReason": "customerCanceled"
},
"returnItemId": "LCFJTDCD7NCZEYE"
}
]
}
Testing
Since you can test in either sandbox or production, take care not to inadvertently impact any production orders with your testing.
Here's a sample workflow you can follow to test the Orders resource:
Create a test order.
In production, orders are created automatically when a customer places an order. In sandbox mode, you have to use
createtestorder
or the Merchant Center UI to create a test order.Production orders move from their starting status to
pendingShipment
automatically. In sandbox mode, you have to use theadvancetestorder
call to advance the order to a pending shipment state. You can also use the APPROVE button in the Merchant Center Orders tab to perform this step.Mark the order as
Shipped
and thenDelivered
either through the UI or withshiplineitems
andupdateshipment
.Create a test return.
In production, customers initiate returns.In sandbox, you can use
createtestreturn
orcreateorderreturn
. Note that you can get the required request parameterslineItemId
andquantity
by callingorders.get
for a particular order.Call
orderreturns.list
,orderreturns.get
,orderreturns.acknowledge
, andorderreturns.process
methods to make queries and process order returns.