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:
- Create an order.
- Advance order status.
- List all orders.
- Acknowledge order.
- Assign Merchant Order ID.
- Charge customer.
- Create shipment.
- 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
orlist
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.