Order Returns API

The Order Returns API v2.1 is an optional API that uses the following methods:

An order can be returned by a customer's request through Google Customer Service, or by using the Google Shopping portal to request a return.

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 orderreturns.process or returnrefundlineitem is made.

orderreturns.list

The orderreturns.list method filters account returns based on optional query parameters, and 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.1/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-8984-80-0722 and TEST-4329-83-8262 respectively:


{
  "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

The orderreturns.get method gets one order's return based on the returnId specified. To find the returnId, use the orderreturns.list method to discover a production order's returnId, or save the returned returnId when creating a test return with the createtestreturn sandbox call.

Example URL for the orderreturns.get method:

GET https://www.googleapis.com/content/v2.1/merchantID/orderreturns/returnId

The following is a sample response body for orderreturns.get. 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

The orderreturns.acknowledge method is used to acknowledge a return and to set the status of the order return parameter acknowledged as True. This call can be used to mark the return orders that have been downloaded and a subsequent orderreturns.list call can be used to retrieve a list of newest returns filtered by ack parameter.

The following example illustrates a successful API call and the Request and Response JSON:

POST
https://www.googleapis.com/content/v2.1/merchantId/orderreturns/returnId/acknowledge

Request JSON:

{
  "operationId": "ack_op_1"
}

Successful 200 OK Response JSON:

{
  "kind": "content#orderreturnsAcknowledgeResponse",
  "executionStatus": "executed"
}

orderreturns.process

Once you have found a return using the orderreturns.list or orderreturns.get method, you take action on the returned item using the orderreturns.process API.

The following examples show the Request and Response JSON for:

  1. A full refund example due to a customer cancellation shown as "returnRefundReason": "customerCanceled".
  2. A partial refund example due to a customer cancellation shown as "returnRefundReason": "customerCanceled".

Sample URL to process the return :

POST
https://www.googleapis.com/content/v2.1/merchantId/orderreturns/returnId/process

The following JSON example shows a full refund:

{
  "operationId": "process_op_1",
  "refundShippingFee": {
    "fullRefund": true,
    "reasonText": "canceled",
    "returnRefundReason": "customerCanceled"
  },
  "returnItems": [
    {
      "refund": {
        "fullRefund": true,
        "reasonText": "canceled",
        "returnRefundReason": "customerCanceled"
      },
      "returnItemId": "LCFJTDCD7NCZEYE"
    }
  ]
}

JSON Response for a successful processing of the full refund:

{
  "kind": "content#orderreturnsProcessResponse",
  "executionStatus": "executed"
}

The following JSON Request example to process the return of an item for a partial refund:

{
  "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"
    }
  ]
}

JSON Response for a successful processing of the partial refund return:

{
  "kind": "content#orderreturnsProcessResponse",
  "executionStatus": "executed"
}

Content API V2 to V2.1 changes

Though not directly related to the orderreturns resource, if you are using the v2 orders.returnlineitem or v2 orders.refund method to process a return, these two methods are replaced by the new orders.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 a pending shipment state, and you can use the APPROVE button 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 you can get the required request parameters lineItemId and quantity by calling orders.get for a particular order.

  4. Call the orderreturns.list, orderreturns.get, orderreturns.acknowledge, and orderreturns.process methods to make queries and process order returns.