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. To do this, check the checkbox at Merchant Center > Purchases on Google > Settings.
- Configure a new project.
As part of this step, you will download a JSON key file which you may need to edit, as
described in Service account key.
For additional information, see Configure a Google Console Project.
- Add the "Purchases on Google Order Manager" role to your new Google Service Account (GSA) that was created in the previous step. Do this for any other account that will use the Orders API or access the Orders view in 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 Google Service Account (GSA) and any other accounts that will access the Orders API or the Orders view in Merchant Center.
To assign the order manager role:
- Open the Merchants Center.
- Click the 3 dots in the upper right and select Users:
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 an account 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. Repeat this process for all accounts that will access the Orders API or the Orders view in Merchant Center.
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 environment. 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 ("v2"): For your live order processing, use production mode
by specifying "/v2" for the mode in your URLs. For example:
- Sandbox mode ("v2sandbox"): 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.