About Orders

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.

Currently, the Purchases on Google program only supports orders with one line item, but Google Express supports multiple line items. Since this will also be supported by the Purchases on Google program in the future, we strongly recommend planning for multiple line item support, even if you only plan on participating in the Purchases on Google program. For that reason, we’ve included order templates that will help you in doing such tests.

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 'shipped'.

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.

Overview

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:

  1. Order creation: An order is created when a customer completes a purchase through either Purchases on Google or Google Express Merchant Direct. The order is created in Google’s Order Management System (OMS), with the status of 'In Progress'. For a period of time after ordering (approximately 30 minutes), 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.

  2. Retrieving orders (not in diagram): After an order is placed, merchants can retrieve it using list.

    Having said that, while an order's status is "inProgress", we encourage merchants to reserve inventory, but not to start the fulfillment process. Instead, wait until the 30-minute period passes and the order moves to a status of "pendingShipment".

  3. Acknowledging orders (optional): Sets the value of the order's acknowledged field to "true". While optional, we recommend that merchants use the API to acknowledge an 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)

      OR

    • When the order is pending shipment: represented by the second dotted line (3)
  4. Preparing for shipment: 30 minutes after an order is placed, the order will advance to a status of "pendingShipment". At this point, funds are secured by Google and the order is confirmed for fulfillment.

  5. Setting the Merchant Order ID (optional) (not in diagram): While also optional, we recommend merchants update the Merchant Order ID with updatemerchantorderid after 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.

  6. Shipping orders: As products ship, Merchants can notify Google via the shiplineitems method. 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.
  7. 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).
  8. Processing returns: If a product is returned, merchants can use the returnlineitem call. 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.

Item Transitions

Order Transitions

Send feedback about...

Content API for Shopping