Order Returns API

Overview

You can use the following Order Returns API v2.1 methods to manage your returns:

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

Content API v2 to v2.1 changes

The v2 methodsorders.returnlineitem and orders.refund are replaced by orderreturns.creatOrderReturn and orderreturns.process in v2.1.

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 API:

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

  2. Mark the order as Shipped and then Delivered either through the UI or with shiplineitems and updateshipment.

  3. Create a test return.

    In production, customers initiate returns.In sandbox, you can use createtestreturn or createorderreturn. Note that you can get the required request parameters lineItemId and quantity by calling orders.get for a particular order.

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