Order Invoices API

Overview

The Order Invoices API is an order API that allows for much more detailed invoicing but requires changes in the life cycle of an order if you are currently integrated with the Orders API.

When using createchargeinvoice to create an invoice for an order, you cannot use returnrefundlineitem to get refunds; you must use createrefundinvoice instead. If a particular order has not had createchargeinvoice called, then createrefundinvoice cannot be used and refund (or the related refund and return calls) will have to be used in its place.

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 (note: not all these are needed in all places)
    • Pre-tax price
    • Taxes
    • Fees
    • Promotions
    • Other amounts
  • The new system is incompatible with the refund method.
  • createrefundinvoice will be used instead of refund, returnrefundlineitem, and returnlineitem.
  • You must call createchargeinvoice after shiplineitems.

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 refund API you will need to do a few things to get it to use the new Invoices API. This list represents the minimum (there is more information in the rest of the document):

  • Add the shippingGroupId field to your shiplineitems call.
  • Call createchargeinvoice after the shiplineitems call.
  • Call createrefundinvoice instead of refund, returnlineitem, or returnrefundlineitem.

shiplineitems

The 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://www.googleapis.com/content/v2/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": [
        "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"
      }
    }
  }
}

Values

A positive value in any section means that the entity represented by the section (merchant, customer, or Google) receives that amount; a negative value means that they are charged that amount. The entity represented in individual invoices (the items in the lineItemInvoices section) is implicitly the merchant, so a positive number means that is what the merchant is paid.

Example of positive and negative amounts in the createchargeinvoice body (merchant is being paid and customer is being charged)

...
    "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"
      }
    },
...

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." The taxes can be sales tax or other kinds of fees (recycling, ewaste, etc.). 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",
        "unit1"
      ],
      "unitInvoice": {
        "unitPricePretax": {
          "value": "140",
          "currency": "USD"
        },
        "unitPriceTaxes": [
          {
            "taxType": "sales",
            "taxAmount": {
              "value": "14",
              "currency": "USD"
            }
          }
        ]
      }
    },
...

You can also specify promotions and additional charge amounts. Currently, the only allowed "additional charge amounts" are shipping charges.

Example of line item invoice with additional charges

...
  "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"
                  }
                }
              }
            ]
          }
        ]
      }
    }
  ],
...

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 don't need to be unique.

Example of identical shipmentUnitIds

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

If all the units are exactly the same, you can give them all the same unit id in which case you would repeat the same unit id for each unit.

Example of unique 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 it's 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 and promotionSummaries subsections.

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 the promotionSummaries part

...
    "promotionSummaries": [
      {
        "promotionId": "tbby123_us",
        "promotionAmount": {
          "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://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

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.

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",
            "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"
          }
        }
      }
    }
  ]
}

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, the promotions, 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",
    "unit1"
],
...

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"
          }
        }
      }
    }
  ]
...