Orders resource

Stay organized with collections Save and categorize content based on your preferences.

Before using the orders resource, follow the steps in Get started with orders.

Here's how to make a simple transaction using the Orders resource:

  1. Create an order.
  2. Advance order status.
  3. List all orders.
  4. Acknowledge order.
  5. Assign Merchant Order ID.
  6. Charge customer.
  7. Create shipment.
  8. Update order status.

All examples use sandbox mode by specifying /v2.1sandbox in the URL. You can remove sandbox to run the examples in a production environment with /v2.1.

Create an order

Make sure you can authenticate your Merchant Center account through the Orders resource. Then, use createtestorder with the following URL and an order template to create an order in sandbox mode.

POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/testorders
{
  "templateName": "template1"
}

A successful call returns the orderId of the new order:

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

(Sandbox only) Advance order status

Approved orders have the status pendingShipment. In production mode, the order status updates automatically. In sandbox mode you have to update the status to pendingShipment yourself.

To change the status of an order to pendingShipment, call advancetestorder:

POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/testorders/order_ID/advance

Here's a sample call:

POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/testorders/G-PLA-7877-86-2240/advance
{
  "orderId": "G-PLA-7877-86-2240"
}

To confirm that the status is updated, use get:

GET https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240

List all orders

You can use list to list all your current orders:

GET https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/

We recommend a 10 minute poll rate.

You can add acknowledged=false to a list call to only list orders that haven't been acknowledged yet:

GET https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/?acknowledged=false

Acknowledge order

You can use acknowledge to set the order status to acknowledged:

The acknowledge call requires an operationId that you can use to re-run requests and prevent duplicate operations. You set the operationId yourself.

POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240/acknowledge
{
  "operationId": "operation-1"
}

Assign Merchant Order ID

After acknowledging an order, you can assign a Merchant Order ID with updatemerchantorderid. The value you assign should be unique within your Merchant Center account, but there are no constraints beyond that. We recommend using the same order ID as your order management system.

POST https://www.googleapis.com/content/v2.1sandbox/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.

Charge customer

You can make an optional call to captureOrder the customer before shipping their order. You only need to call captureOrder once per order.

Note that successfully charging a customer doesn't result in an immediate disbursement of payment to your account.

POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240/captureOrder

captureOrder returns whether or not charging the customer was successful. If successful, you can ship the order. If unsuccessful, there may be an issue with the customer's or merchant's billing. You can cancel the order instead of shipping, or try again later.

Create shipment

You can create a new shipment with shiplineitems.

You must include the following in the body of the request:

shipmentId
The ID of the shipment.
operationId
The ID you choose when you acknowledge an order.
lineItems[].lineItemId
The Item ID from the Orders Resource in the response from a get or list call.
lineItems[].quantity
The number of items being shipped. Must be at least 1.

When the API creates a shipment, it sets the order's status to shipped if all items in the order are shipped, or partiallyShipped if only some items in the order are shipped.

Here's a sample shiplineitems call:

POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240/shipLineItems
{
  "operationId": "operation-4",
  "shipmentId": "shipment-1",
  "lineItems": [
    {
      "lineItemId": "CYBIDQWXDKCZEYE",
      "quantity": 1
    }
  ],
  "carrier": "FedEx",
  "trackingId": "ASDFGHJKL12347890"
}

Update order status

When the shipment(s) arrive, you can update the shipment's status to delivered with updateshipment.

Use the shipmentId that you set when you created the shipment with shiplineitems. You can find the shipmentID in the response from get after you ship the order.

Here's a sample updateshipment call:

POST https://www.googleapis.com/content/v2.1sandbox/merchant_ID/orders/G-PLA-7877-86-2240/updateShipment
{
  "operationId": "operation-5",
  "shipmentId": "shipment-1",
  "status": "delivered"
}

After this, the order is complete.

You can explore the other calls available to you in the Reference documentation and learn about known issues in Limits & Constraints.