概览
Order Invoices API 是订单 API。如果您已经集成了 Orders API，使用此订单 API 可以进行更详细的结算，但需要更改订单的生命周期。
使用 createchargeinvoice 为订单创建帐单时，您不能使用 returnrefundlineitem 退款，而必须改用 createrefundinvoice。如果特定的订单尚未调用 createchargeinvoice，则不能使用 createrefundinvoice，而必须改用 refund（或相关的 refund 和 return 调用）。
现有代码更改摘要
旧工作流与新工作流之间的主要区别是：
- 新系统允许提供更详细的价格信息，包括（注意：并非所有位置都需要这些信息）
- 税前价格
- 税费
- 费用
- 促销活动
- 其他金额
- 新系统与
refund方法不兼容。 - 将使用
createrefundinvoice，而不是refund、returnrefundlineitem和returnlineitem。 - 您必须在
shiplineitems之后调用createchargeinvoice。
要使用 Order Invoices API，您必须在 createchargeinvoice 之后调用 shiplineitems，以标识配送组并指定订单的价格结构。
本文档会进行详细介绍，但是概括来说，如果有代码使用旧的 refund API，则您需要执行几项操作，以便此代码可以使用新的 Invoices API。此列表只列出了最精简的内容，文档的其余部分会进行详细说明。
- 将
shippingGroupId字段添加到您的shiplineitems调用中。 - 调用
shiplineitems之后，再调用createchargeinvoice。 - 调用
createrefundinvoice，而不是refund、returnlineitem或returnrefundlineitem。
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"
}
},
...
订单项
对于每个订单项，您需要指定 lineItemId 或 productId。
使用 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 子部分和可选的 additionalChargeSummaries 和 promotionSummaries 子部分。
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 中设置的相同字段执行详细退款，将退款金额按订单项级别上的商品费用、税费和费用进行细分。实质上，createrefundinvoice 是 createchargeinvoice 的相反的。
您需要首先使用 createchargeinvoice，然后才能使用 createrefundinvoice。
仅退款或者退款并退货
您可以选择使用 refundOnlyOption 仅退款或者使用 returnOption 进行退货。您只能并且必须使用其中一项。
退款但不退货的示例
...
"refundOnlyOption": {
"reason": "adjustment",
"description": "Missed Shipping Date"
},
...
退款并退货的示例
...
"returnOption": {
"reason": "customerDiscretionaryReturn",
"description": "Ordered By Mistake"
},
...
配送组和单位 ID
要引用 createrefundinvoice，您需要指定在原始 createchargeinvoice 调用中指定的 shipmentGroupId 和 shipmentUnitIds。
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"
}
}
}
}
]
...