The
orderinvoices
resource is a resource that allows you to tell Google what the customer paid for
and how much you should be paid in a much more detailed way than you can with
just the orders.shiplineitem
method. However, using this resource requires
changes in the life cycle of an order if you are currently integrated with the
orders
resource.
After using orderinvoices.createchargeinvoice
to create an invoice for an
order, if a customer requests a refund directly (not through Google) you must
use orderinvoices.createrefundinvoice
to process the refund. If a customer
requests a refund through Google, we recommend using orderreturns.process
(v2.1 only), which is simpler than orderinvoices.createchargeinvoice
. You
can also use orders.refunditem
(v2.1 only) to generate refunds without
marking items as returned. If you are using v2 of the Content API, you must use
orderinvoices.createchargeinvoice
instaed of orders.refund
or
orders.returnrefundlineitem
, regardless of how the refund was requested.
v2 to v2.1 changes
The principal differences between the old workflow and the new workflow are:
The new system allows for more detail in the pricing including
- Pre-tax price
- Taxes
- Fees
- Other amounts
The new system is incompatible with the
refund
method.For refund requests not initiated through Google, you must call
orderinvoices.createrefundinvoice
instead oforderreturns.process
to process the return.You must call
orderinvoices.createchargeinvoice
afterorders.shiplineitems
.
To use the Order Invoices resource, you must call the
orderinvoices.createchargeinvoice
after orders.shiplineitems
to identify the
shipping groups and specify the pricing structure of the order.
This document goes into much more detail but briefly, if you have code that uses
the old (v2) refund
method, you will need to do a few things to get it to
use the new Order Invoices resource. This list represents the minimum; there is
more information in the rest of the document.
- Add the
shippingGroupId
field to yourorders.shiplineitems
call. - Call
orderinvoices.createchargeinvoice
after theorders.shiplineitems
call. - Call
orderinvoices.createrefundinvoice
instead oforders.refund
ororders.returnrefundlineitem
.
orders.shiplineitems
The Order Invoices resource begins with the orders.shiplineitems
call. The call is the same
as before except for one addition: the shipmentGroupId
which is a new required
field. In general, we have the following two use cases:
Line items with same charges (most common)
If the line items do not have different charges (for example, the same product
value, shipping charges, etc.) based on which shipment they are in, you should
use the same shipmentGroupId
for all the orders.shiplineitems
calls.
Here's a sample call to orders.shiplineitems
with one shipmentGroupId
:
{
"operationId": "ship1",
"lineItems": [
{
"lineItemId": "YYFPTREDYNCZEYE",
"quantity": 2
},
{
"productId": "online:en:US:df4sg53ds9",
"quantity": 1
}
],
"shipmentGroupId": "shipmentgroup1",
"shipmentInfos": [
{
"shipmentId": "shipment1",
"carrier": "UPS",
"trackingId": "1234567890"
}
]
}
Subsequent calls use the same shipmentGroupId
.
Line items with different charges (less common)
If the line items have different shipping charges, for example, source warehouse,
weight based rates, etc., you can differentiate charges using different
shipmentGroupId
s (a less common case). The only reason to have different
shipmentGroupId
values within the same order is if you want to create different
invoices for those items. If you want to do that you need to call orders.shiplineitems
once for each separate shipmentGroupId
.
Here's a series of calls using unique shipmentGroupId
s:
shipmentgroup1
{
"operationId": "ship1",
"lineItems": [
{
"productId": "online:en:US:d3k3245",
"quantity": 2
}
],
"shipmentGroupId": "shipmentgroup1",
"shipmentInfos": [
{
"shipmentId": "shipment1",
"carrier": "UPS",
"trackingId": "1234567890"
}
]
}
shipmentgroup2
{
"operationId": "ship2",
"lineItems": [
{
"productId": "online:en:US:df4sg53ds9",
"quantity": 1
}
],
"shipmentGroupId": "shipmentgroup2",
"shipmentInfos": [
{
"shipmentId": "shipment2",
"carrier": "UPS",
"trackingId": "1234567891"
}
]
}
orderinvoices.createchargeinvoice
Once you have called orders.shiplineitems
for a set of items, you need to create an
invoice. You do that by calling the
orderinvoices.createchargeinvoice
method.
POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderinvoices/orderId/createChargeInvoice
POST https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderinvoices/orderId/createChargeInvoice
You need to call orderinvoices.createchargeinvoice
at least once for each
shipmentGroupId
that you set in orders.shiplineitems
.
Here's a sample orderinvoices.createchargeinvoice
call with two line items, one of which has two units:
{
"invoiceId": "invoice1", // Defined by merchant
"operationId": "charge1",
"shipmentGroupId": "shipmentgroup1",
"lineItemInvoices": [
{
"productId": "online:en:US:d3k3245",
"shipmentUnitIds": [// Quantity of 2
"unit1",
"unit2"
],
"unitInvoice": {
"unitPricePretax": {
"value": "70",
"currency": "USD"
},
"unitPriceTaxes": [
{
"taxType": "sales",
"taxAmount": {
"value": "7",
"currency": "USD"
}
}
]
}
},
{
"productId": "online:en:US:df4sg53ds9",
"shipmentUnitIds": [// Quantity of 1
"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": "679.85",
"currency": "USD"
},
"tax": {
"value": "67.85",
"currency": "USD"
}
},
"additionalChargeSummaries": [
{
"totalAmount": {
"pretax": {
"value": "21.35",
"currency": "USD"
},
"tax": {
"value": "2.13",
"currency": "USD"
}
},
"type": "shipping"
}
]
}
}
Line items
For each line item, you need to specify either the
lineItemId
or the
productId
.
lineItemId from orders.list
...
"lineItemInvoices": [
{
"lineItemId": "5VYPTREPXNCZEYE",
...
productId
...
"lineItemInvoices": [
{
"productId": "online:en:US:df4sg53ds9",
...
Each line item invoice consists of a pretax price (a value and a currency) which is required and zero or more "taxes" (sales tax).
There is also a section called shipmentUnitIds
, but let's ignore that for now;
we'll get back to it in a bit.
Sample line item invoice
...
"lineItemInvoices": [
{
"productId": "online:en:US:d3k3245",
"shipmentUnitIds": [
"unit1",
"unit2"
],
"unitInvoice": {
"unitPricePretax": {
"value": "70",
"currency": "USD"
},
"unitPriceTaxes": [
{
"taxType": "sales",
"taxAmount": {
"value": "7",
"currency": "USD"
}
}
]
}
},
...
You can also specify additional charge amounts. Currently, the only allowed "additional charge amounts" are shipping charges. The shipping charges can be associated with any of the line items.
Sample line item invoice with additional charges
...
"lineItemInvoices": [
{
"productId": "online:en:US:d3k3245",
"shipmentUnitIds": [
"unit1",
"unit2"
],
"unitInvoice": {
"unitPricePretax": {
"value": "70",
"currency": "USD"
},
"unitPriceTaxes": [
{
"taxType": "sales",
"taxAmount": {
"value": "7",
"currency": "USD"
}
}
],
"additionalCharges": [
{
"type": "shipping",
"additionalChargeAmount": {
"pretax": {
"value": "21.35",
"currency": "USD"
},
"tax": {
"value": "2.13",
"currency": "USD"
}
},
}
]
}
}
],
...
Unit IDs
A unit is considered to be an individual quantity of single line item. Each unit
needs to be assigned a unit ID in the shipmentUnitIds
field per line item.
These unit IDs should be unique:
...
"shipmentUnitIds": [
"unit1",
"unit2"
],
...
In this example (with unique unit IDs) some of the units are different—for example, one of them might be free because of a "buy one get one free" deal.
In this example, the unit that the customer paid for has unit1
as its ID while
the one that is free has unit2
. If you need to refund the customer for one of
them you can specify which one is being refunded by using the unit ID you
specified in this call. In this scenario, you would specify unit2
first
because that one was free.
Invoice summary
At the end of the orderinvoices.createchargeinvoice
there is the summary section. This has
two parts: the total and the breakdown among the entities involved. The summary
is divided into the required productTotal
subsection and the optional
additionalChargeSummaries
subsection.
Example of InvoiceSummary
...
"invoiceSummary": {
"productTotal": {
"pretax": {
"value": "561.20",
"currency": "USD"
},
"tax": {
"value": "55.98",
"currency": "USD"
}
},
...
Example of additionalChargeSummaries
...
"additionalChargeSummaries": [
{
"type": "shipping",
"totalAmount": {
"pretax": {
"value": "1.98",
"currency": "USD"
},
"tax": {
"value": "0.10",
"currency": "USD"
}
}
}
],
...
Example of order:get resource
{
"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://www.gstatic.com/shopping-content-api/product_images/chromecast.jpg",
"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://www.gstatic.com/shopping-content-api/product_images/nexus_9.jpg",
"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"
}
}
orderinvoices.createrefundinvoice
POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderinvoices/orderId/createRefundInvoice
POST https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderinvoices/createRefundInvoice
You can use
orderinvoices.createrefundinvoice
to offer customers a complete or partial refund, or complete a return for an
order. This can be, for example, because the customer requested a refund or
return, or because you wanted to give them a discount or refund for any other
reason. For refund requests initiated through Google, we recommend using
orderreturns.process
(v2.1 only), which is simpler to use than
orderinvoices.createchargeinvoice
.
Example orderinvoices.createrefundinvoice body
{
"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",
"unit2"
],
"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"
}
}
}
}
]
}
This example is a literal inverse of the charge invoice shown earlier, refunding it completely. Note that you could refund it partially.
Same fields as orderinvoices.createchargeinvoice
You use the same fields you set up in orderinvoices.createchargeinvoice
to execute a
detailed refund that breaks down the refund amounts by product cost, taxes, and
fees on a line item level. Essentially, orderinvoices.createrefundinvoice
is
orderinvoices.createchargeinvoice
in reverse.
You cannot use orderinvoices.createrefundinvoice
without having used orderinvoices.createchargeinvoice
first.
Refund only or refund and return
You have the option to do a refund only or return by using the
refundOnlyOption
or returnOption
. You can only use one of these, and you
must use one or the other.
Refund without return
...
"refundOnlyOption": {
"reason": "adjustment",
"description": "Missed Shipping Date"
},
...
Refund with return
...
"returnOption": {
"reason": "customerDiscretionaryReturn",
"description": "Ordered By Mistake"
},
...
Shipment group and unit IDs
To reference the orderinvoices.createrefundinvoice
you need to specify the shipmentGroupId
and shipmentUnitIds
that you specified in the original orderinvoices.createchargeinvoice
call.
Example shipmentGroupId
...
"shipmentGroupId": "shipmentgroup1",
...
For each set of unit IDs within a line item you need to specify the pre-tax price, the taxes and fees, and the additional charges. If the values for one unit are different from the other units in that line item you can separate them; if they are the same you can keep them together.
Example shipmentUnitIds
...
"shipmentUnitIds": [
"unit1",
"unit2"
],
...
For a total refund the values will all be the same as in the charge invoice created earlier. For partial refund the values would have to be less than or equal to the values in the charge invoice—you cannot give back more than they paid originally.
Example of productTotal section
...
"invoiceSummary": {
"productTotal": {
"pretax": {
"value": "-561.20",
"currency": "USD"
},
"tax": {
"value": "-55.98",
"currency": "USD"
}
},
...
Finally, you need to specify the summary.
Example summary
...
"invoiceSummary": {
"productTotal": {
"pretax": {
"value": "-561.20",
"currency": "USD"
},
"tax": {
"value": "-55.98",
"currency": "USD"
}
}
}
...
Test the Order Invoices resource
Test orderinvoices.createchargeinvoice
Testing create test order is somewhat involved. Let's start with an overview.
Create a test order.
- Get a template json body.
- Add
"enableOrderinvoices": true
. - Call "create test order".
Advance the test order.
Call
shiplineitem
on the test order.All
orderinvoices.createchargeinvoice
on the test order.- Construct the body.
- Make the call.
Sample test order
Since the whole rest of this document is devoted to explaining how this resource works, here we'll just give you a series of concrete example for testing purposes.
Create test order
{
"testOrder": {
"enableOrderinvoices": true,
"customer": {
"fullName": "Pam Beesly",
"email": "pam@example.com",
"explicitMarketingPreference": false,
"marketingRightsInfo": {
"explicitMarketingPreference": "denied",
"lastUpdatedTimestamp": "2018-10-01T22:17:33Z"
}
},
"lineItems": [{
"product": {
"offerId": "d3k3245",
"channel": "online",
"targetCountry": "US",
"contentLanguage": "en",
"title": "Google Chromecast",
"price": {
"value": "70.00",
"currency": "USD"
},
"condition": "new",
"gtin": "00811571013579",
"brand": "Google",
"mpn": "H2G2-42",
"imageLink": "http://www.gstatic.com/shopping-content-api/product_images/chromecast.jpg"
},
"quantityOrdered": 2,
"unitTax": {
"value": "7.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": {
"offerId": "df4sg53ds9",
"channel": "online",
"targetCountry": "US",
"contentLanguage": "en",
"title": "Nexus 9",
"price": {
"value": "399.85",
"currency": "USD"
},
"condition": "new",
"gtin": "00821793042684",
"brand": "HTC",
"mpn": "99HZF001-00",
"variantAttributes": [{
"dimension": "color",
"value": "lunar white"
},
{
"dimension": "memory",
"value": "16 GB"
},
{
"dimension": "connectivity",
"value": "Wi-Fi only"
}
],
"itemGroupId": "123",
"imageLink": "http://www.gstatic.com/shopping-content-api/product_images/nexus_9.jpg"
},
"quantityOrdered": 1,
"unitTax": {
"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"
}
}
],
"predefinedDeliveryAddress": "pam",
"paymentMethod": {
"type": "AMEX",
"lastFourDigits": "5678",
"predefinedBillingAddress": "jim",
"expirationMonth": 9,
"expirationYear": 2020
},
"shippingCost": {
"value": "21.35",
"currency": "USD"
},
"shippingCostTax": {
"value": "2.13",
"currency": "USD"
},
"shippingOption": "standard"
}
}
Advance test order
Call orders.hiplineitems
{
"operationId": "dave2",
"lineItems": [{
"productId": "online:en:US:d3k3245",
"quantity": 2
},
{
"productId": "online:en:US:df4sg53ds9",
"quantity": 1
}
],
"shipmentGroupId": "shipmentgroup1",
"shipmentInfos": [{
"shipmentId": "SHIPMENT1",
"carrier": "UPS",
"trackingId": "1234567890"
}]
}
POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orders/orderId/shipLineItems
Call orderinvoices.createchargeinvoice
Please see the examples elsewhere in this document.
Test orderinvoices.createrefundinvoice
Using the order we already created, you'll now create an order return for it.
- Mark order delivered.
- Mark order returned.
- Call
orderinvoices.createrefundinvoice
on order.
Mark order delivered
{
"operationId": "dave3",
"status": "delivered",
"shipmentId": "SHIPMENT1"
}
POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orders/orderId/updateShipment
Mark order returned
{
"items": [
{
"lineItemId": "<lineitem>",
"quantity": <quantity>
}
]
}
POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orders/orderId/testreturn
Call orderinvoices.createrefundinvoice
Please see examples in the body of this document.