Orders API

Introduction

The new Orders API enables merchants to process orders received through the Purchases on Google and Google Express Merchant Direct programs in Google Shopping. Please note that this program is only available to select partners while it’s in Beta mode. Through this API, participating merchants are able to receive and acknowledge new orders, reflect their progress shipping them, and provide credits or refunds in response to returns or other events.

The API offers both a Sandbox mode and a Production mode. The Sandbox is a great place to experiment and issue your first requests. It is also where new API features may first appear.

To access production methods, use 'v2' in the URL. To access sandbox methods, use the 'v2sandbox' version of the URL. Note that the gettestordertemplate, createtestorder, and advancetestorder methods are available only at the sandbox URL. For example, here are the 2 URLs for the list method:

  • Production:
    GET 'https://www.googleapis.com/content/v2/merchantId/orders/'
    
  • Sandbox:
    GET 'https://www.googleapis.com/content/v2sandbox/merchantId/orders/'
    

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 Merchant Direct 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.

Life 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.
Sandbox note: Orders created in the Sandbox may be erased by Google from the system 1 month after placement.

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.
    Sandbox Note: In the Sandbox environment, orders can be artificially created using createtestorder.
  2. Retrieving orders (not in diagram) - After an order is placed, merchants can retrieve it using list. Having said that, while an order is in the 'In progress' state, 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) - While optional, we recommend that merchants use the API to acknowledge an order as soon as it is ingested into their own order management systems. 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.
    You can acknowledge an order either:
    • 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)
  4. Preparing for shipment - About 30 minutes after an order is placed, the order will advance to a status of 'Pending Shipment'. At this point, funds are secured by Google and the order is confirmed for fulfillment.
    Sandbox Note - In the Sandbox environment, an order will not advance to 'Pending Shipment' automatically on a timer. Developers can cause an order to do so using advancetestorder.
  5. Setting the Merchant Order ID (optional) (not in diagram) - While also optional, we recommend merchants update the Merchant Order ID on Google’s OMS once such a value is available in the merchant's order management system . This orderId 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) - Once 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.
  9. Initiating Refunds (not in diagram) - 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.

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

A note about client libraries

Our client libraries are available here. You may use these to make requests to the Orders API directly. However, those requests would reach real production orders, not the Sandbox. To reach the Orders Sandbox API, override the URL of the request to point to v2sandbox instead of v2, as shown below:

  • Production:
    'https://www.googleapis.com/content/v2/'
    
  • Sandbox:
    'https://www.googleapis.com/content/v2sandbox/'
    
However, if you choose, there are Sandbox-specific libraries available which make all requests to the Sandbox.

As a reminder, gettestordertemplate, createtestorder, and advancetestorder are only available in Sandbox, and if used in production will return an error.

Create your first order

After ensuring you can authenticate with your Merchant Center account through the API, you are ready to create your first order in the Sandbox using the createtestorder call. Note that the Google account you are using to access the Merchant Center must be enrolled in either the Purchases on Google or Google Express Merchant Direct programs, in addition to your Merchant Center's enrollment. Please contact us to ensure that your Google accounts are enrolled. Make the call to the URL endpoint described below, and use the templateName parameter to specify a canned order that you can use to get started with the API. Currently, there are 2 templates, 'template1' and 'template2'. Template1 is an example of a multi-product order, whereas template2 is single-product.

POST content/v2sandbox/merchantId/testorders
{
  templateName: "template1"
}

If you are successful, you will get a response similar to this. Note that the response contains the orderId of the order that was just created:

{
 "kind": "content#ordersCreateTestOrderResponse",
 "orderId": "G-PLA-7877-86-2240"
}

Now that you have an order created in your account, let's take a look at the actions you can take.

(Sandbox only) Advance your order

Normally, orders will move from their starting status of 'inProgress' to 'pendingShipment' automatically, approximately 30 minutes after the order was placed. However, in the Sandbox, this is left in control of the developer, and orders will not advance to pendingShipment automatically. You must make a call to advancetestorder to move orders to the 'pendingShipment' status.

Outside of the sandbox, once an order has a status of 'pendingShipment', you can be assured that the order is confirmed and you can begin shipping the order.

Making this request is very simple; simply POST to this url endpoint with your order ID and merchant ID filled in the URL, with an empty body.

POST 'content/v2sandbox/merchantId/testorders/G-PLA-7877-86-2240/advance'

You can confirm that the status has been updated by using the get request:

GET 'content/v2sandbox/merchantId/orders/G-PLA-7877-86-2240'

Once the order is advanced to 'pendingShipment', you are ready to move on to the next stage of processing.

List and acknowledge orders

This next section focuses on some of the preprocessing steps that are involved in successfully using the Orders API.

List the orders in your account

While you would know the order ID of the order you just created, in practice, these orders will be coming in from customers who have just clicked 'Purchase', so you won't have the order ID just yet.

To get a handle on that, use list to find new orders to process:

GET 'content/v2sandbox/merchantId/orders/'

This simple call will list out all the orders in your Merchant Center account. Once you know you have an order in your account, you can take some actions on it to make it easier to work with. We recommend using a poll rate of about once every 10 minutes.

Acknowledge the order(s) you have received

When you have processed a new order's arrival, mark it as acknowledged. You can do this by using acknowledge.

POST 'content/v2sandbox/merchantId/orders/G-PLA-7877-86-2240/acknowledge'
{
  "operationId": "operation-1"
}

The acknowledge call takes one argument, the 'operationId', which is a field that will show up frequently in the API, and should be unique across operations on the same order. The value is used to enable retries of requests and prevent accidental duplicate operations in the event of errors such as timeouts.

The acknowledge call will enable you to make future 'list' calls with the added filter of acknowledge=false, listing only orders which have not yet been acknowledged, making processing of new orders much easier.

GET 'content/v2sandbox/merchantId/orders/?acknowledged=false'

Assign a Merchant Order ID

Now that you have acknowledged the order, you may choose to optionally assign a 'Merchant Order ID' to it. This value should be unique within a Merchant Center account, but there are no constraints beyond that. We highly recommend using the actual order ID used by your own order management system, so that both systems share a unique key, which might come in handy for any reconciliations needed. Do this by using updatemerchantorderid.

POST 'content/v2sandbox/merchantId/orders/G-PLA-7877-86-2240/updateMerchantOrderId'
{
  "operationId": "operation-2",
  "merchantOrderId": "uniqueValueWithinMerchantCenterAccount"
}

Once you have assigned this value, you can query for your orders using the ID you have assigned the order via getbymerchantorderid.

Time to pack it up! Shipping your order

Once you are ready to ship your order, you can create a new shipment using shiplineitems. When shipping line items, you will need the lineItemId, which can be obtained from the Orders Resource, in the response to a 'get' or 'list' call. Shipments are created with a status of 'shipped'.

POST 'content/v2sandbox/merchantId/orders/G-PLA-7877-86-2240/shipLineItems'
{
  "operationId": "operation-3",
  "shipmentId": "shipment-1",
  "lineItems": [
    {
      "lineItemId": "CYBIDQWXDKCZEYE",
      "quantity": 1
    }
  ],
  "carrier": "FedEx",
  "trackingId": "ASDFGHJKL12347890"
}
  

Order Delivery

Once the shipments have arrived, you may choose to optionally update those shipments to a status of 'delivered' using updateshipment. Be sure to match the shipmentId used when the shipment was created. You can find this value in the response from the Orders.get call once you've shipped the order.

POST 'content/v2sandbox/merchantId/orders/G-PLA-7877-86-2240/updateShipment'
{
  "operationId": "operation-4",
  "shipmentId": "shipment-1",
  "status": "delivered"
}

At this stage, the order is complete! You've successfully fulfilled your first order through the Orders API. Explore the other calls available to you in the API Reference documentation, and learn about any existing issues to be aware of in Known Issues.

Limits and constraints

Quotas and rate limits

The API is free to use and has no published quotas or rate limits. While we don't expect any merchant to bump into limits, please reach out to us if you do and we'll be happy to evaluate your case.

Cancelled orders

Orders that are cancelled with a noIventory reason will lead to the removal of the product from POG until you make an update to that product. This will not affect your Shopping ads.

Order ship times

Currently, if an order is not shipped within 30 days, Google will automatically cancel the order. The cancellation reason will be 'orderTimeout'. This value cannot be set by merchants as a cancellation reason.

Order of operations of custombatch

Custombatch order of operations are not guaranteed. Do not include in the same batch request any operations which depend on another operation in the same batch. From a conceptual point of view, assume that all operations in a batch are executed simultaneously, and that the order of operations is nondeterministic. This generally means not putting operations affecting the same orderId in the same batch, though there are exceptions to this rule of thumb.

Request frequency

As a best practice, wait for a response to a request on an order before executing a second request. For example, since request data can sometimes take some time to propagate through our system, we do not guarantee that a GET request made immediately after making a POST will reflect the changes. If you receive a successful response from your POST request, that is sufficient proof that the POST request was executed. There is no need to issue a GET request to 're-confirm' this.

Known Issues

Since the API Sandbox is still in a preview, we have a number of known issues that we are working on resolving. We will try to keep this list up to date with the latest version of the API.

list

The maxResults field is not implemented yet, but will be available soon with a default of 25 results and a max value allowed of 250.

The orderBy field does not support ASC for the time being. It only supports DESC.

actor attribute

There is an 'actor' attribute in refunds, cancellations, and returns, which can be used to determine who initiated those respective actions. However, this field is not yet available in refunds and returns of the Orders object. The field will be available in the future.

Send feedback about...

Content API for Shopping