The Orders API enables merchants to process orders received through the Purchases on Google and Google Express Merchant Direct programs in Google Shopping. Through this API, participating merchants can:
- Receive and acknowledge new orders
- Reflect their progress shipping them
- Provide credits or refunds in response to returns or other events
Get started with the Orders API
To use the Orders API:
- Enroll your Merchant Center account in either the "Purchases on Google" or "Google Express Merchant Direct" programs. (This is in addition to your Merchant Center's enrollment.) Please contact us to ensure that your Google accounts are enrolled.
- Agree to the Purchases on Google terms in your Merchant Center account (check the checkbox at Merchant Center > Purchases on Google > Settings).
- Configure a Google Console Project:
- Create a new project (if one doesn't already exist).
- Enable the Content API for Shopping for the project.
- Create a Google Service Account (GSA).
- Download the key as a JSON file. You may need to edit this file, as described in Service account key.
- Add the new GSA to your Merchant Center account. Be sure that you:
- Use the correct email address for the GSA (it ends in "@developer.gserviceaccount.com").
- Add the "Purchases on Google Order Manager" role to the GSA, as described in Assign the order manager role.
Repeat this step for all accounts that will use the Orders API or access the Orders view in the Merchant Center.
- (Optional) Download the Content API client libraries for your app.
- Modify the API key (if you are making calls through a web service and not using a library).
- Implement OAuth 2.0 authentication in your app. Alternatively, you can get an access token to include in your RESTful requests, as described in Getting an access token.
- Call the Orders API. Use sandbox mode to test your Orders API implemention before deploying it to production. We also provide a quick tutorial for trying out the API.
Assign the order manager role
Before you can use the Orders API, you must assign the role of "Purchases on Google Order Manager" to your GSA and any other accounts that will access the Orders API or the Orders view in the Merchant Center.
To assign the order manager role:
- Open the Merchants Center.
- Click the 3 dots in the upper right and select Users:
The Merchant Center displays a list of users and their roles.
If you do not see the Users option in the drop-down list, your account does not have administrative privileges.
- Click a user's row to edit it. The User Preferences view displays.
If your GSA is not in the user list, click the + icon to add it.
- In the User access section, check the
Purchases on Google Order Manager checkbox, as the following example
- Click the Save button to save your changes.
The Purchases on Google Order Manager role should appear next to the user in the user list.
Sandbox and production modes
You can use the Orders API in one of two modes, depending on whether you are building and testing your implementation in a sandbox, or you are deploying it to a production envirionment. Sandbox mode might also be where new API features can first be used.
You indicate which version you want to use in the URL:
Where merchant_ID is your Merchant Center ID and mode specifies which mode to use:
- Production mode: For your live order processing, use production mode by
specifying "/v2" for the mode in your URLs. For example:
- Sandbox mode: For experimenting and issuing test requests, use sandbox mode by
specifying "/v2sandbox" for the mode in your URLs. For example:
Sandbox mode supports the following additional methods that production mode does not:
Tutorial: Using the "Try the API" functionality
To quickly create test orders in sandbox mode, use the "Try this API" box on
the right hand side of the
createtestorder documentation page. The ability to try the API
functionality works on all of the API documentation pages.
To create a test order with "Try this API":
- Open the API Reference and navigate to the
Note that "Try this API" calls the method whose documentation you are currently viewing. For example, if you are viewing the
createtestorderreference page, the "Try this API" feature calls
createtestorder. To call
get, navigate to the
- Enter your merchant ID in the
merchantIdrequest parameter field.
- Add the
templateNamefield to the request body, and set it to one of the templates described below (for example, "template1").
The following example shows a simple call with merchant ID "42":
- Click the Execute button.
The Orders API creates a new test order and responds with an HTTP 200. The response includes the order ID of the newly created order, as the following example shows:
- Copy the value of
orderIdfrom the response. You can use the order's ID in Next steps.
After creating a test order, you can move it through the process of acknowledgement and shipping while setting its status each step of the way. A common workflow includes the following:
- See the contents of the newly created order with the
getmethod. You can also use
listto get a list of all orders.
- Advance your order's status to "pendingShipment" with
- Acknowledge the receipt of the order with
- Optionally assign a Merchant Order ID with
shiplineitemsto create a shipment for your order and change its status to "shipped".
- Finish up by setting the shipment's status to "delivered" with
These steps are described in detail in Using the Orders API.
Google provides the following pre-populated order templates that have been created so that you
don’t have to type in all of the details. These can be called using the template parameter in the
- "template1": Two products/skus, quantities of 2 and 1, no promotion
- "template1a": Two products/skus, quantities of 2 and 1, free shipping promotion
- "template1b": Two products/skus, quantities of 2 and 1, specific product promotion
- "template2": One product/sku, quantity of 2, no promotion
As you can see from the templates, the Orders API supports sending orders with multiple products/skus with different quantities.
You can see the different template data by calling
gettestordertemplate with your
merchant ID and the name of the template you want to view.