Using the Orders API

Before you can use the Orders API, be sure that you follow the steps in Get started with the Orders API.

The following steps summarize the Orders API calls you make to process a simple transaction. Each of these steps are described below:

  1. Create your first order.
  2. Advance your order's status to "pendingShipment".
  3. List the orders in your account.
  4. Acknowledge that you received the order.
  5. Assign a Merchant Order ID to the order.
  6. Create a new shipment.
  7. Update your order's status to "delivered".

These examples use base_url to refer to "https://www.googleapis.com". In addition, all examples use sandbox mode by specifying "/v2sandbox" in the URL. In a production environment, you would replace that with "/v2".

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 sandbox mode using the createtestorder call.

Call 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. The available templates are described in Order templates.

POST base_url/content/v2sandbox/merchant_ID/testorders
{
  "templateName": "template1"
}

On a successful call, Google responds with a response that contains the orderId of the order that was just created, as the following example shows:

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

(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 sandbox mode, this is left in your control, and orders will not advance to "pendingShipment" automatically.

To change the status of an order to "pendingShipment", call advancetestorder using the following syntax:

POST base_url/content/v2sandbox/merchant_ID/testorders/order_ID/advance

In the body of the request, set orderId to the ID of the order you created. For example:

POST base_url/content/v2sandbox/merchant_ID/testorders/G-PLA-7877-86-2240/advance
{
  "orderId": "G-PLA-7877-86-2240"
}

In production mode, once an order has a status of "pendingShipment", you can be assured that the order is confirmed and you can begin shipping the order.

To confirm that the status has been updated, use get:

GET base_url/content/v2sandbox/merchant_ID/orders/G-PLA-7877-86-2240

After advancing an order to "pendingShipment", you are ready to move on to the next stage of processing.

List and acknowledge orders

This 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 base_url/content/v2sandbox/merchant_ID/orders/

This simple call lists all the orders in your Merchant Center account. Once you know you have an order in your account, you can take 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, as the following example shows:

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

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

Note that you can add acknowledged=false to a list call, which then lists only orders which have not yet been acknowledged. This makes processing new orders easier. For example:

GET base_url/content/v2sandbox/merchant_ID/orders/?acknowledged=false

Assign a Merchant Order ID

After acknowledging an order, you can optionally assign a Merchant Order ID to it with updatemerchantorderid. The value you assign 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.

POST base_url/content/v2sandbox/merchant_ID/orders/G-PLA-7877-86-2240/updateMerchantOrderId
{
  "operationId": "operation-2",
  "merchantOrderId": "unique_value_within_mc_account"
}

After assigning a Merchant Order ID, you can query for a specific order using getbymerchantorderid.

Time to pack it up! Ship your order

Once you are ready to ship your order, you can create a new shipment using shiplineitems.

When calling shiplineitems to create a shipment, you must include the following in the body of the request:

When Google creates a shipment for an order, it sets the order's status to "shipped" (if all items in the original order were shipped) or "partiallyShipped" (if some items from the original order have not yet been shipped).

The following example shows a sample shiplineitems call:

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

Update order status

Once the shipments have arrived, you can optionally update the shipment's status to "delivered" using updateshipment.

Be sure to match the shipmentId that you set when you created the shipment with shiplineitems. You can find this value in the response from the get call after you've shipped the order.

The following example shows an updateshipment call:

POST base_url/content/v2sandbox/merchant_ID/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 Limits & Constraints.

Send feedback about...

Content API for Shopping