We will sunset v2 of the Content API on March 29th, 2021. To avoid disruptions with your integration, please migrate to v2.1 as soon as possible. For more information, see Migrating to v2.1.

Order Returns API

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

Customers can return an order through the Google Shopping portal, by contacting Google Customer Service, or by returning an item in store. Merchants can use orderReturns service to process in-store or mail-in returns, refund returns via different forms of payments (original, cash or in-store credit), or reject a return.

Regardless of the option used to initiate a return, the Order assumes the returned or partiallyReturned status only if the following criteria are met:

  • The merchant accepts the return.
  • The merchant calls orderreturns.process or ordereturns.createorderreturn and then (optionally) orderreturns.process.

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

For sandbox requests:

GET https://www.googleapis.com/content/v2.1sandbox/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

For sandbox requests:

GET https://www.googleapis.com/content/v2.1sandbox/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

For sandbox requests:

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

Request JSON:

{
  "operationId": "ack_op_1"
}

Successful 200 OK Response JSON:

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

orderreturns.createorderreturn

You can create a new order return using orderreturns.createorderreturn, and issue refunds using orderreturns.process. When creating a return using orderreturns.createorderreturn, you can define its return type using the returnShipmentType field in the request, which accepts the following values:

  • inStore: Indicates that the return is initiated at a physical store.
  • byMail: Indicates that the return is sent in by mail.

The following example shows the request and response JSON for creating a new order return.

Sample URL to process the return:

POST https://www.googleapis.com/content/v2.1/merchantID/orderreturns/createOrderReturn

For sandbox requests:

POST https://www.googleapis.com/content/v2.1sandbox/merchantID/orderreturns/createOrderReturn

The following request JSON example shows how to create an order return:

{
  "orderId": ”TEST-8984-80-0722”,
  "operationId": “operation-uuid-1234”,
  "returnMethodType": ”inStore”,
  "lineItems": [
    {
      “lineItemId”: “LKGJTDCD7NCZEYE”,
      “quantity”: 3
    }
  ],
}

JSON response for a successful creation of the return:

{
  "kind": "content#orderreturnsCreateorderreturnResponse",
  "executionStatus": "executed",
  “merchantOrderReturn”: Object(MerchantOrderReturn)
}

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

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

Full refunds can only work with paymentType as originalFop. If you want to refund as cash or credit, you must use partialRefund to inform Google of the specific amount you have issued. See the In-Store Returns section for examples and more information.

Sample URL to process the return :

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

For Sandbox: POST https://www.googleapis.com/content/v2.1sandbox/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"
}

In-Store Returns

If you have physical store locations, your customers can initiate a return at your store and receive refunds via original form of payment, in cash or in-store credit.

To process in-store returns, first, look up an order return using the orderId with orderreturns.list with Google order id parameter. Then, if an order return is not found, create a return using orderreturns.createorderreturn and set the returnMethodType to inStore. Note that you can get the required request parameters lineItemId and quantity by calling orders.get for the order.

Example request:

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

For sandbox requests: POST https://www.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/createOrdeReturn

{
  "orderId": ”TEST-8984-80-0722”,
  "operationId": “operation-uuid-1234”,
  "returnMethodType": ”inStore”,
  "lineItems": [
    {
      “lineItemId”: “LKGJTDCD7NCZEYE”,
      “quantity”: 3
    }
  ],
}

After an order return is found or created, you can check the refundable amount of each line item in the MerchantOrderReturn object which tells you the amount to be refunded to the customer using orderreturns.process. You can use orderreturns.process to issue refunds to the customer’s original form of payment, in cash, or store credit by paymentType, which accepts the following values:

  • originalFop: Refund is made to the customer’s original payment method.
  • cash: Refund is made as cash back to the customer in-store.
  • credit: Refund is made to the customer by giving credits.

You can only issue a full refund with originalFop as the paymentType. If you refund via cash or credit, you must use partialRefund to inform Google about the specific refund amount you have issued. Google does not validate the amount refunded if it is refunded as cash or store credit.

The following example shows a request for refunding to customer in cash:

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

For sandbox requests:

POST  https://www.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/returnId/process
{
  "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"
    }
  ]
}

Content API V2 to V2.1 changes

If you are using the v2 orders.returnlineitem and orders.refund methods to process returns, these methods are replaced by orderreturns.creatOrderReturn and orderreturns.process 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, you can use the createtestreturn call or createorderreturn 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.