Order Returns API

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:

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:

  1. 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.

  2. Mark as Shipped and then Delivered either via the UI or making API calls shiplineitems and updateshipment respectively.

  3. 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 parameters lineItemId and quantity by making the Orders:get call for a particular Order.

  4. Call the orderreturns:list or get methods to get the return details required.