Order Returns API

Order Returns API 是一个可选 API,它使用以下方法:

  • orderreturns.list 用来确定多个已退货订单。

  • orderreturns.get 用来确定单个已退货订单。

客户通过 Google 客户服务或使用 Web 应用请求从订单门户退回订单。

无论选择用哪种方法发起退货,仅在以下情况时,Order 才假定为 returnedpartiallyReturned 状态

orderreturns.list

orderreturns.list 方法根据可选的查询参数过滤帐号退货情况,并为退回的每个 Order 返回唯一的 orderReturnId 标识符。此 ReturnIdget 方法中仅用于返回特定 Order 退货的具体结果。

orderreturns.list 方法的示例网址:

GET https://www.googleapis.com/content/v2/{merchantID}/orderreturns

以下是 orderreturns.list 的示例响应主体,包含两个订单及其各自的退货。它们的订单 ID (orderId) 分别是 TEST-4755-72-4132TEST-3499-90-3352

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

orderreturns.get 方法基于指定的 returnId 获取一个订单的退货。orderreturns.list 方法返回生产订单的 returnId,而沙盒中的 createtestreturn 调用返回已创建的退货的 returnId

orderreturns.get 方法的示例网址:

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

以下是 orderreturns.get 的示例响应主体。此示例包含 orderId: TEST-4755-72-4132(其已在上面的 orderreturns.list 调用中返回)的两件退货商品:

{
 "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 到 V2.1 的变化

虽然与 orderreturns 资源没有直接联系,但是如果您要使用 returnlineitemrefund 方法处理退货,这两种方法在 v2.1 中已替换为新的 returnrefundlineitem 方法。

测试 Order Returns API

由于可以在沙盒或生产环境中进行测试,因此请注意不要在测试时不经意影响任何生产订单。以下是适用于各个环境的详细步骤:

  1. 创建测试订单。

    在生产环境中,当您的客户下订单时,系统会自动创建 Order。但是,在沙盒模式下,您必须使用 createtestorder 调用或 Merchant Center 界面功能来创建测试订单。

    订单自动从 inProgress 起始状态转变为 pendingShipment。但是,在沙盒模式下,您必须使用 advancetestorder 调用将订单转到待发货状态,并且您可以使用 Merchant Center“订单”标签页中的 APPROVE Action 更轻松、更快捷地执行此步骤。

  2. 通过界面,或者通过分别发出 API 调用 shiplineitemsupdateshipment,可以将订单标记为 Shipped,然后标记为 Delivered

  3. 创建测试退货。

    在生产环境中,这是由客户通过其“订单”门户或通过 Google 客户服务发起的。在沙盒中,客户必须使用 createtestreturn 调用。请注意,通过对特定 Order 发出 Orders:get 调用,客户可以获得所需的请求参数 lineItemId 和数量。

  4. 调用 orderreturns:listget 方法来获取所需的退货详情。