The Order Invoices API is
an order API 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 API requires changes in the life
cycle of an order if you are currently integrated with the Orders
API.
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 API, you must use
orderinvoices.createchargeinvoice
instaed of orders.refund
or
orders.returnrefundlineitem
, regardless of how the refund was requested.
Summary of changes to existing code
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
createchargeinvoice
aftershiplineitems
.
To use the Order Invoices API, you must call the createchargeinvoice
after
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
API you will need to do a few things to get it to use the new
Order Invoices API. This list represents the minimum; there is more information
in the rest of the document.
- Add the
shippingGroupId
field to yourshiplineitems
call. - Call
orderinvoices.createchargeinvoice
after theorders.shiplineitems
call. - Call
orderinvoices.createrefundinvoice
instead oforders.refund
ororders.returnrefundlineitem
.
shiplineitems
The Order Invoices API begins with the 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:
Use case 1 (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 shiplineitems
calls.
shiplineitems call example with one shipmentGroupId (subsequent shiplineitems calls will use the same shipmentGroupId)
{
"operationId": "ship1",
"lineItems": [
{
"lineItemId": "YYFPTREDYNCZEYE",
"quantity": 2
},
{
"productId": "online:en:US:df4sg53ds9",
"quantity": 1
}
],
"shipmentGroupId": "shipmentgroup1",
"shipmentInfos": [
{
"shipmentId": "shipment1",
"carrier": "UPS",
"trackingId": "1234567890"
}
]
}
Use case 2 (less common)
If the line items have different shipping charges, for example, source warehouse,
weight based rates, etc., you can differentiate charges using different
shipmentGroupIds
(a much rarer 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 shiplineitems
once for each separate shipmentGroupId
.
shiplineitems example for shipmentgroup1
{
"operationId": "ship1",
"lineItems": [
{
"productId": "online:en:US:d3k3245",
"quantity": 2
}
],
"shipmentGroupId": "shipmentgroup1",
"shipmentInfos": [
{
"shipmentId": "shipment1",
"carrier": "UPS",
"trackingId": "1234567890"
}
]
}
shiplineitems example for shipmentgroup2
{
"operationId": "ship2",
"lineItems": [
{
"productId": "online:en:US:df4sg53ds9",
"quantity": 1
}
],
"shipmentGroupId": "shipmentgroup2",
"shipmentInfos": [
{
"shipmentId": "shipment2",
"carrier": "UPS",
"trackingId": "1234567891"
}
]
}
createchargeinvoice
Once you have called shiplineitems
for a set of items, you need to create an
invoice. You do that by calling the
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'll need to call createchargeinvoice
at least once for each
shipmentGroupId
that you set in shiplineitems
.
Example of a createchargeinvoice body
Example 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
.
Line item specified with lineItemId returned in Orders.list
...
"lineItemInvoices": [
{
"lineItemId": "5VYPTREPXNCZEYE",
...
Line item specified with 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.
Example of one simple 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.
Example of 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.
Example of identical shipmentUnitIds
...
"shipmentUnitIds": [
"unit1",
"unit2"
],
...
In this second 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 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 the InvoiceSummary section header and the productTotal part
...
"invoiceSummary": {
"productTotal": {
"pretax": {
"value": "561.20",
"currency": "USD"
},
"tax": {
"value": "55.98",
"currency": "USD"
}
},
...
Example of the additionalChargeSummaries part
...
"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"
}
}
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
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 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 createchargeinvoice
You use the same fields you set up in createchargeinvoice
to execute a
detailed refund that breaks down the refund amounts by product cost, taxes, and
fees on a line item level. Essentially, createrefundinvoice
is
createchargeinvoice
in reverse.
You cannot use createrefundinvoice
without having used 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.
Example of refund without return
...
"refundOnlyOption": {
"reason": "adjustment",
"description": "Missed Shipping Date"
},
...
Example of refund with return
...
"returnOption": {
"reason": "customerDiscretionaryReturn",
"description": "Ordered By Mistake"
},
...
Shipment group and unit IDs
To reference the createrefundinvoice
you need to specify the shipmentGroupId
and shipmentUnitIds
that you specified in the original createchargeinvoice
call.
Example of the shipmentGroupId specification
...
"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 of the shipmentUnitIds specification
...
"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 the productTotal section
...
"invoiceSummary": {
"productTotal": {
"pretax": {
"value": "-561.20",
"currency": "USD"
},
"tax": {
"value": "-55.98",
"currency": "USD"
}
},
...
Finally, you need to specify the summary.
Example showing the merchant, customer, and Google parts
...
"invoiceSummary": {
"productTotal": {
"pretax": {
"value": "-561.20",
"currency": "USD"
},
"tax": {
"value": "-55.98",
"currency": "USD"
}
}
}
...
Testing the Order Invoices API
Testing 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
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 API 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 Shiplineitems for order
{
"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 createchargeinvoice for order
Please see the examples elsewhere in this document.
Testing createrefundinvoice
Using the order we already created, you'll now create an order return for it.
- Mark order delivered.
- Mark order returned.
- Call
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 createrefundinvoice
Please see examples in the body of this document.