This section describes the structure and lifecycle of an order in the Orders API.
Structure of an order
An order contains line items, and those line items refer to products. Orders can be placed on those products in certain quantities. For example, an order that includes 2 Chromecasts and 1 Nexus 6 would be represented as having 2 line items, with the Chromecast products having a quantity of 2 and the Nexus 6 product having a quantity of 1.
An order also captures additional purchase-time information, like the shipment method selected by the customer, their shipping and billing address, and their preferences for receiving emails from the merchant. For a full description of what’s included in an order, please see the Orders Resource page.
If an order is modified, for example due to items being shipped, or a refund having been granted, this information will also be displayed in the details of the Order Resource.
Each order has an order status, which summarizes the progress
towards completion of the order. The order status is frequently derived
from the actual line items. For example, if all line items have been
shipped, the order status will be
Orders API IDs
The Orders API has a number of different IDs which are used to describe a number of different actions:
- Google Order ID
- This value is assigned by Google when an order is created, and is unique across all orders, even across different Merchant Center accounts.
- Merchant Order ID
- This value is assigned by the merchant after the order has been created. It must be unique within a Merchant account.
- Line Item ID
- This value is assigned by Google when an order is created, and identifies a line item within an order. Line items contain details about what was ordered, such as product, quantity, tax, and the offer ID.
- Shipment ID
- This value is assigned by the merchant when creating a new shipment. It must be unique within a given order's lifetime.
- Operation ID
- This value is assigned by the merchant when performing any operation on orders using this API. It is used for detecting duplicate requests, and must be unique within the lifetime of a single order.
Lifecycle of an Order
An order is typically created by a customer choosing to buy a product on Google Shopping. The order then moves through a series of statuses as the merchant receives, processes, and ships the order.
At a high level, the flow of actions looks as follows. Keep in mind that this is simplified view of the statuses that an order can have, this is not meant to be an exhaustive diagram:
Order creation: An order is created when a customer completes a purchase through Shopping Actions. The order is created in Google's Order Management System (OMS), with the status of "In Progress". While the order status is "In Progress", the customer is able to cancel the order by simply clicking the Cancel button on Google's Order Confirmation page. After this time passes, the order can not be cancelled by the customer, though the merchant can cancel an order at any time until it has been shipped.
In sandbox mode, orders can be artificially created using
Retrieving orders (not in diagram): After an order is placed, merchants can retrieve it using
While an order's status is
inProgress, we encourage merchants to reserve inventory, but not to start the fulfillment process until the order has a status of
Acknowledging orders (optional): Sets the value of the order's
true. While optional, we recommend that merchants use the API to
acknowledgean order as soon as it is ingested into their own OMS. That way, when requesting new orders via the list call, merchants can filter on orders that haven't been acknowledged yet, and obtain only the list of orders that are pending ingestion.
Calling any method on a given order other than retrieving its details (or using
advancetestorder, in the Sandbox) will automatically acknowledge the order. This can take place during the following parts of the flow:
When the order is in progress: represented by the first dotted line (3)
When the order is pending shipment: represented by the second dotted line (3)
Preparing for shipment: Some time after an order is placed, a valid order will advance to a status of
pendingShipment. At this point, funds are secured by Google and the order is confirmed for fulfillment.
In sandbox mode, an order will not advance to
pendingShipmentautomatically on a timer. Developers can cause an order to do so using
Setting the Merchant Order ID (optional) (not in diagram): While also optional, we recommend merchants update the Merchant Order ID with
updatemerchantorderidafter such a value is available in the merchant's OMS.
This order ID will be passed back to the merchant upon retrieving the order details in future calls and can help with reconciliations, acting as a unique key present in both the merchant's and Google's OMS.
Shipping orders: As products ship, Merchants can notify Google via the
shiplineitemsmethod. Merchants can ship the entirety of the products in an order, or a subset of them. We also highly recommend passing along the shipment's tracking ID of the shipment, if available. Note that shipping products triggers a corresponding charge on the customer’s payment instrument.
Marking Shipments as Delivered (optional): After a shipment is delivered, merchants can notify Google via
updateshipment. For most transactions, this is the last step (if you have access to shipment delivery data).
Processing returns: If a product is returned, merchants can use the
returnrefundlineitemcall. Note that declaring an item as returned does not refund the customer.
Not shown in the diagram above are the following additional actions that affect the status of an order:
- Initiating refunds
- Refunds are noted in the API via
refund. Refunds can be issued before or after shipment, and do not alter the status of an order.
- Cancelling items
- Cancel an item from an order by using
cancellineitem. This removes the item from the order and refunds the cost of that item.
- Cancelling orders
- Cancel an entire order by using
cancel. This results in a full refund.
Item and order state transitions
Below are diagrams explaining valid transitions for line items and orders. In general the state of an order is derived from the state of its line items, but it can be useful to have an idea of what states these objects can be in. Please use these diagrams as a guide for conceptual understanding.