Order Invoices API

概览

Order Invoices API 是订单 API。如果您已经集成了 Orders API,使用此订单 API 可以进行更详细的结算,但需要更改订单的生命周期。

使用 createchargeinvoice 为订单创建帐单时,您不能使用 returnrefundlineitem 退款,而必须改用 createrefundinvoice。如果特定的订单尚未调用 createchargeinvoice,则不能使用 createrefundinvoice,而必须改用 refund(或相关的 refund 和 return 调用)。

现有代码更改摘要

旧工作流与新工作流之间的主要区别是:

  • 新系统允许提供更详细的价格信息,包括(注意:并非所有位置都需要这些信息)
    • 税前价格
    • 税费
    • 费用
    • 促销活动
    • 其他金额
  • 新系统与 refund 方法不兼容。
  • 将使用 createrefundinvoice,而不是 refundreturnrefundlineitemreturnlineitem
  • 您必须在 shiplineitems 之后调用 createchargeinvoice

要使用 Order Invoices API,您必须在 createchargeinvoice 之后调用 shiplineitems,以标识配送组并指定订单的价格结构。

本文档会进行详细介绍,但是概括来说,如果有代码使用旧的 refund API,则您需要执行几项操作,以便此代码可以使用新的 Invoices API。此列表只列出了最精简的内容,文档的其余部分会进行详细说明。

  • shippingGroupId 字段添加到您的 shiplineitems 调用中。
  • 调用 shiplineitems 之后,再调用 createchargeinvoice
  • 调用 createrefundinvoice,而不是 refundreturnlineitemreturnrefundlineitem

shiplineitems

Invoices API 以 shiplineitems 调用开始。此调用与以前相同,除了添加了 shipmentGroupId(这是新的必填字段)。一般情况下,我们有以下两个用例:

用例 1(最常见)

根据订单项所属运单,如果订单项没有不同的扣款金额(例如,同一商品价值、运费等),则您应对所有 shiplineitems 调用使用同一 shipmentGroupId

具有一个 shipmentGroupId 的 shiplineitems 调用示例(后续 shiplineitems 调用将使用同一 shipmentGroupId)

{
  "operationId": "ship1",
  "lineItems": [
    {
    "lineItemId": "YYFPTREDYNCZEYE",
      "quantity": 2
    },
    {
      "productId": "online:en:US:df4sg53ds9",
      "quantity": 1
    }
  ],
  "shipmentGroupId": "shipmentgroup1",
  "shipmentInfos": [
    {
      "shipmentId": "shipment1",
      "carrier": "UPS",
      "trackingId": "1234567890"
    }
  ]
}

用例 2(不常见)

如果订单项的运费(例如,源仓库、基于重量的费率等)不同,则您可以使用不同的 shipmentGroupIds 来区分费用(这种情况很少见)。只有想要为订单项创建不同的帐单时,才需要在同一订单内使用不同的 shipmentGroupId 值。如果要执行此操作,您需要为每个单独的 shipmentGroupId 调用一次 shiplineitems

shipmentgroup1 的 shiplineitems 示例

{
  "operationId": "ship1",
  "lineItems": [
    {
    "productId": "online:en:US:d3k3245",
      "quantity": 2
    }
  ],
  "shipmentGroupId": "shipmentgroup1",
  "shipmentInfos": [
    {
      "shipmentId": "shipment1",
      "carrier": "UPS",
      "trackingId": "1234567890"
    }
  ]
}

shipmentgroup2 的 shiplineitems 示例

{
  "operationId": "ship2",
  "lineItems": [
      {
      "productId": "online:en:US:df4sg53ds9",
      "quantity": 1
    }
  ],
  "shipmentGroupId": "shipmentgroup2",
  "shipmentInfos": [
    {
      "shipmentId": "shipment2",
      "carrier": "UPS",
      "trackingId": "1234567891"
    }
  ]
}

createchargeinvoice

为一组商品调用 shiplineitems 后,您需要创建帐单。通过调用 createchargeinvoice 方法,您可以完成此操作。

POST https://www.googleapis.com/content/v2/merchantId/orderinvoices/orderId/createChargeInvoice

对于您在 shiplineitems 中设置的每个 shipmentGroupId,您需要至少调用一次 createchargeinvoice

createchargeinvoice 正文示例

示例 createchargeinvoice 调用包含两个订单项,其中一个订单的单位 2 个

{
  "invoiceId": "invoice1",  // Defined by merchant
  "operationId": "charge1",
  "shipmentGroupId": "shipmentgroup1",
  "lineItemInvoices": [
    {
      "productId": "online:en:US:d3k3245",
      "shipmentUnitIds": [
        "unit1",
        "unit1"   // Quantity of 2
      ],
      "unitInvoice": {
        "unitPricePretax": {
          "value": "140",
          "currency": "USD"
        },
        "unitPriceTaxes": [
          {
            "taxType": "sales",
            "taxAmount": {
              "value": "14",
              "currency": "USD"
            }
          }
        ]
      }
    },
    {
      "productId": "online:en:US:df4sg53ds9",
      "shipmentUnitIds": [
        "unit1"
      ],
      "unitInvoice": {
        "unitPricePretax": {
          "value": "399.85",
          "currency": "USD"
        },
        "unitPriceTaxes": [
          {
            "taxType": "sales",
            "taxAmount": {
              "value": "39.85",
              "currency": "USD"
            }
          }
        ],
        "additionalCharges": [
          {
            "type": "shipping",
            "additionalChargeAmount": {
              "pretax": {
                "value": "21.35",
                "currency": "USD"
              },
              "tax": {
                "value": "2.13",
                "currency": "USD"
              }
            }
          }
        ]
      }
    }
  ],
  "invoiceSummary": {
    "productTotal": {
      "pretax": {
        "value": "561.20",
        "currency": "USD"
      },
      "tax": {
        "value": "55.98",
        "currency": "USD"
      }
    }
  }
}

任何部分中的正值都表示按部分(商家、客户或 Google)展示的实体收到此金额。负值表示扣除此金额。在各个帐单中出现的实体(lineItemInvoices 部分中的商品)实际上是商家,因此正数表示付给商家的金额。

createchargeinvoice 正文中的正负金额的示例(付给商家和从客户扣款)

...
    "merchantBalance": {
      "pretax": {
        "value": "561.20",
        "currency": "USD"
      },
      "tax": {
        "value": "55.98",
        "currency": "USD"
      }
    },
    "customerBalance": {
      "pretax": {
        "value": "-561.20",
        "currency": "USD"
      },
      "tax": {
        "value": "-55.98",
        "currency": "USD"
      }
    },
...

订单项

对于每个订单项,您需要指定 lineItemIdproductId

使用 lineItemId(在 Orders.list 中返回)指定的订单项

...
 "lineItemInvoices": [
    {
      "lineItemId": "5VYPTREPXNCZEYE",
...

使用 productId 指定的订单项

"lineItemInvoices": [
    {
      "productId": "online:en:US:df4sg53ds9",

每个订单项帐单由税前价格(必填,包含值和货币)以及零个或零个以上“税费”组成。税费可以是销售税费或其他种类的费用(回收再利用、电子垃圾等)。还有一个称为 shipmentUnitIds 的部分,但现在我们忽略此部分,稍后再回顾。

一个简单的订单项帐单示例

...
 "lineItemInvoices": [
    {
      "productId": "online:en:US:d3k3245",
      "shipmentUnitIds": [
        "unit1",
        "unit1"
      ],
      "unitInvoice": {
        "unitPricePretax": {
          "value": "140",
          "currency": "USD"
        },
        "unitPriceTaxes": [
          {
            "taxType": "sales",
            "taxAmount": {
              "value": "14",
              "currency": "USD"
            }
          }
        ]
      }
    },
...

您还可以指定促销活动和其他扣款金额。目前,唯一允许的“其他扣款金额”是运费。

包含其他扣款金额的订单项帐单示例

...
  "lineItemInvoices": [
    {
      "productId": "online:en:US:d3k3245",
      "shipmentUnitIds": [
        "unit1",
        "unit1"
      ],
      "unitInvoice": {
        "unitPricePretax": {
          "value": "140",
          "currency": "USD"
        },
        "unitPriceTaxes": [
          {
            "taxType": "sales",
            "taxAmount": {
              "value": "14",
              "currency": "USD"
            }
          }
        ],
        "promotions": [
          {
            "promotionId": "tbby123_us",
            "promotionAmount": {
              "pretax": {
                "value": "5",
                "currency": "USD"
              },
              "tax": {
                "value": "0.5",
                "currency": "USD"
              }
            }
          }
        ],
        "additionalCharges": [
          {
            "type": "shipping",
            "additionalChargeAmount": {
              "pretax": {
                "value": "21.35",
                "currency": "USD"
              },
              "tax": {
                "value": "2.13",
                "currency": "USD"
              }
            },
            "additionalChargePromotions": [
              {
                "promotionId": "tbby123_us",
                "promotionAmount": {
                  "pretax": {
                    "value": "5",
                    "currency": "USD"
                  },
                  "tax": {
                    "value": "0.5",
                    "currency": "USD"
                  }
                }
              }
            ]
          }
        ]
      }
    }
  ],
...

单位 ID

单位是指单个订单项的个体数量。在每个订单项的 shipmentUnitIds 字段中,每个单位都需要分配一个单位 ID。这些单位 ID 不必是唯一的。

相同 shipmentUnitIds 的示例

...
"shipmentUnitIds": [
    "unit1",
    "unit1"
],
...

如果所有单位完全相同,则可以为它们提供相同的单位 ID。在这种情况下,您将为每个单位重复使用同一单位 ID。

唯一的 shipmentUnitIds 示例

...
"shipmentUnitIds": [
    "unit1",
    "unit2"
],
...

在第二个示例(具有唯一的单位 ID)中,某些单位可能不同。例如,因为“买一赠一”交易,其中一个单位可能免费。

在此示例中,客户支付的单位将 unit1 作为其 ID,而免费的单位具有 unit2。如果您需要为其中一个单位向客户退款,则可以使用您在此调用中指定的单位 ID 来指定为哪个单位退款。在这种情况下,您首先要指定 unit2,因为此单位是免费的。

帐单摘要

createchargeinvoice 的结尾,有摘要部分。其中包括两部分:所涉及实体的总数和细分数。摘要分为必需的 productTotal 子部分和可选的 additionalChargeSummariespromotionSummaries 子部分。

InvoiceSummary 部分标头和 productTotal 部分的示例

...
"invoiceSummary": {
    "productTotal": {
      "pretax": {
        "value": "561.20",
        "currency": "USD"
      },
      "tax": {
        "value": "55.98",
        "currency": "USD"
      }
    },
...

additionalChargeSummaries 部分示例

...
    "additionalChargeSummaries": [
      {
        "type": "shipping",
        "totalAmount": {
          "pretax": {
            "value": "1.98",
            "currency": "USD"
          },
          "tax": {
            "value": "0.10",
            "currency": "USD"
          }
        }
      }
    ],
...

promotionSummaries 部分示例

...
    "promotionSummaries": [
      {
        "promotionId": "tbby123_us",
        "promotionAmount": {
          "pretax": {
            "value": "1.98",
            "currency": "USD"
          },
          "tax": {
            "value": "0.10",
            "currency": "USD"
          }
        }
      }
    ],
...

order:get 资源示例

{
 "kind": "content#order",
 "id": "TEST-4053-85-2702",
 "merchantId": "123205893",
 "channelType": "googleExpress",
 "lineItems": [
  {
   "id": "YQFPTREDYNCZEYE",
   "quantityOrdered": 2,
   "quantityPending": 2,
   "quantityShipped": 0,
   "quantityDelivered": 0,
   "quantityReturned": 0,
   "quantityCanceled": 0,
   "price": {
    "value": "140.00",
    "currency": "USD"
   },
   "tax": {
    "value": "14.00",
    "currency": "USD"
   },
   "shippingDetails": {
    "method": {
     "methodName": "Ground",
     "carrier": "UPS",
     "minDaysInTransit": 1,
     "maxDaysInTransit": 5
    },
    "shipByDate": "2018-10-10T22:17:33Z",
    "deliverByDate": "2018-10-13T22:17:33Z"
   },
   "returnInfo": {
    "isReturnable": true,
    "daysToReturn": 15,
    "policyUrl": "https://support.google.com/store/answer/2411741"
   },
   "product": {
    "id": "online:en:US:d3k3245",
    "offerId": "d3k3245",
    "targetCountry": "US",
    "channel": "online",
    "contentLanguage": "en",
    "price": {
     "value": "70.00",
     "currency": "USD"
    },
    "title": "Google Chromecast",
    "gtin": "00811571013579",
    "brand": "Google",
    "mpn": "H2G2-42",
    "condition": "new",
    "imageLink": "http://store.google.com/chromecast.png",
    "shownImage": "https://encrypted-tbn1.gstatic.com/shopping?q=tbn:ANqp=CAk"
   }
  },
  {
   "id": "YYFPTREDYNCZEYE",
   "quantityOrdered": 1,
   "quantityPending": 1,
   "quantityShipped": 0,
   "quantityDelivered": 0,
   "quantityReturned": 0,
   "quantityCanceled": 0,
   "price": {
    "value": "399.85",
    "currency": "USD"
   },
   "tax": {
    "value": "39.85",
    "currency": "USD"
   },
   "shippingDetails": {
    "method": {
     "methodName": "Standard",
     "carrier": "FedEx",
     "minDaysInTransit": 3,
     "maxDaysInTransit": 6
    },
    "shipByDate": "2018-10-10T22:17:33Z",
    "deliverByDate": "2018-10-13T22:17:33Z"
   },
   "returnInfo": {
    "isReturnable": true,
    "daysToReturn": 14,
    "policyUrl": "https://support.google.com/store/answer/2411741"
   },
   "product": {
    "id": "online:en:US:df4sg53ds9",
    "offerId": "df4sg53ds9",
    "targetCountry": "US",
    "channel": "online",
    "contentLanguage": "en",
    "price": {
     "value": "399.85",
     "currency": "USD"
    },
    "title": "Nexus 9",
    "gtin": "00821793042684",
    "brand": "HTC",
    "mpn": "99HZF001-00",
    "condition": "new",
    "itemGroupId": "123",
    "imageLink": "http://store.google.com/nexus9.png",
    "shownImage": "https://encrypted-tbn1.gstatic.com/shopping?q=tbn:AN&usqp=CAk",
    "variantAttributes": [
     {
      "dimension": "color",
      "value": "lunar white"
     },
     {
      "dimension": "memory",
      "value": "16 GB"
     },
     {
      "dimension": "connectivity",
      "value": "Wi-Fi only"
     }
    ]
   }
  }
 ],
 "status": "pendingShipment",
 "paymentStatus": "paymentSecured",
 "acknowledged": false,
 "shippingOption": "standard",
 "placedDate": "2018-10-24T19:22:38Z",
 "deliveryDetails": {
  "address": {
   "recipientName": "Pam Beesly",
   "streetAddress": [
    "1600 Amphitheatre Parkway",
    "Building 48 1N1C"
   ],
   "locality": "Mountain View",
   "region": "CA",
   "country": "US",
   "postalCode": "94043",
   "fullAddress": [
    "Pam Beesly",
    "1600 Amphitheatre Parkway",
    "Building 48 1N1C",
    "Mountain View, CA 94043",
    "United States"
   ]
  },
  "phoneNumber": "+1 650-555-0000"
 },
 "customer": {
  "fullName": "Pam Beesly",
  "email": "pam@example.com",
  "marketingRightsInfo": {
   "explicitMarketingPreference": "denied",
   "lastUpdatedTimestamp": "2018-10-01T22:17:33Z"
  }
 },
 "paymentMethod": {
  "type": "AMEX",
  "lastFourDigits": "5678",
  "billingAddress": {
   "recipientName": "Jim Halpert",
   "locality": "Scranton",
   "region": "PA",
   "country": "US",
   "postalCode": "18501",
   "fullAddress": [
    "Jim Halpert",
    "Scranton, PA 18501",
    "United States"
   ]
  },
  "phoneNumber": "+1 412-345-6700",
  "expirationMonth": 9,
  "expirationYear": 2020
 },
 "shippingCost": {
  "value": "21.35",
  "currency": "USD"
 },
 "shippingCostTax": {
  "value": "2.13",
  "currency": "USD"
 },
 "netAmount": {
  "value": "617.18",
  "currency": "USD"
 }
}

createrefundinvoice

POST https://www.googleapis.com/content/v2/merchantId/orderinvoices/orderId/createRefundInvoice
POST https://www.googleapis.com/content/v2sandbox/merchantId/orderinvoices/createRefundInvoice/createChargeInvoice

您可以使用 createrefundinvoice 为客户提供全部或部分退款,或完成订单退货。例如,这可能是因为客户要求退款或退货,或者因为出于其他原因,您想要给客户打折或退款。

示例 createrefundinvoice 正文

{
  "invoiceId": "invoice2",
  "operationId": "refund1",
  "returnOption": {  // Item is being returned as well as refunded.
    "reason": "customerDiscretionaryReturn",
    "description": "Didn't like it"
  },
  "shipmentInvoices": [
    {
      "shipmentGroupId": "shipmentgroup1",  // Matches ID defined in shiplineitems.
      "lineItemInvoices": [
        {
          "productId": "online:en:US:d3k3245",
          "shipmentUnitIds": [
            "unit1",
            "unit1"
          ],
          "unitInvoice": {
            "unitPricePretax": {
              "value": "-140",  // Negative because line item is being refunded.
              "currency": "USD"
            },
            "unitPriceTaxes": [
              {
                "taxType": "sales",
                "taxAmount": {
                  "value": "-14",
                  "currency": "USD"
                }
              }
            ]
          }
        },
        {
          "productId": "online:en:US:df4sg53ds9",
          "shipmentUnitIds": [
            "unit1"
          ],
          "unitInvoice": {
            "unitPricePretax": {
              "value": "-399.85",
              "currency": "USD"
            },
            "unitPriceTaxes": [
              {
                "taxType": "sales",
                "taxAmount": {
                  "value": "-39.85",
                  "currency": "USD"
                }
              }
            ],
            "additionalCharges": [
              {
                "type": "shipping",
                "additionalChargeAmount": {
                  "pretax": {
                    "value": "-21.35",
                    "currency": "USD"
                  },
                  "tax": {
                    "value": "-2.13",
                    "currency": "USD"
                  }
                }
              }
            ]
          }
        }
      ],
      "invoiceSummary": {
        "productTotal": {
          "pretax": {
            "value": "-561.20",
            "currency": "USD"
          },
          "tax": {
            "value": "-55.98",
            "currency": "USD"
          }
        },
        "merchantBalance": {
          "pretax": {
            "value": "-561.20",  // Merchant is being charged so value is negative.
            "currency": "USD"
          },
          "tax": {
            "value": "-55.98",
            "currency": "USD"
          }
        },
        "customerBalance": {
          "pretax": {
            "value": "561.20",  // Customer is being refunded so value is positive.
            "currency": "USD"
          },
          "tax": {
            "value": "55.98",
            "currency": "USD"
          }
        },
        "googleBalance": {
          "pretax": {
            "value": "0",
            "currency": "USD"
          },
          "tax": {
            "value": "0",
            "currency": "USD"
          }
        }
      }
    }
  ]
}

从字面上看,此示例与先前显示的扣款帐单相反,即为其全部退款。请注意,您也可以部分退款。

与 createchargeinvoice 相同的字段

您使用在 createchargeinvoice 中设置的相同字段执行详细退款,将退款金额按订单项级别上的商品费用、税费和费用进行细分。实质上,createrefundinvoicecreatechargeinvoice 的相反的。

您需要首先使用 createchargeinvoice,然后才能使用 createrefundinvoice

仅退款或者退款并退货

您可以选择使用 refundOnlyOption 仅退款或者使用 returnOption 进行退货。您只能并且必须使用其中一项。

退款但不退货的示例

...
"refundOnlyOption": {
  "reason": "adjustment",
  "description": "Missed Shipping Date"
},
...

退款并退货的示例

...
"returnOption": {
  "reason": "customerDiscretionaryReturn",
  "description": "Ordered By Mistake"
},
...

配送组和单位 ID

要引用 createrefundinvoice,您需要指定在原始 createchargeinvoice 调用中指定的 shipmentGroupIdshipmentUnitIds

shipmentGroupId 规范示例

...
"shipmentGroupId": "shipmentgroup1",
...

对于订单项中的每组单位 ID,您需要指定税前价格、税费和费用、促销活动以及其他扣款金额。如果一个单位的值与该订单项中的其他单位不同,则您可以将它们分开。如果相同,则可以将它们放在一起。

shipmentUnitIds 规范示例

...
"shipmentUnitIds": [
    "unit1",
    "unit1"
],
...

对于退款总额,这些值将与之前创建的扣款帐单中的值相同。对于部分退款,这些值必须小于或等于扣款帐单中的值,也就是说您退还的金额不能超过最初支付的金额。

productTotal 部分示例

...
      "invoiceSummary": {
        "productTotal": {
          "pretax": {
            "value": "-561.20",
            "currency": "USD"
          },
          "tax": {
            "value": "-55.98",
            "currency": "USD"
          }
        },
...

最后,您需要指定摘要。

显示商家、客户和 Google 配件的示例

...
      "invoiceSummary": {
        "productTotal": {
          "pretax": {
            "value": "-561.20",
            "currency": "USD"
          },
          "tax": {
            "value": "-55.98",
            "currency": "USD"
          }
        }
      }
    }
  ]
...