The Orders API enables merchants to process orders they receive through Buy on Google.
You can use the Orders API to do the following:
- Receive and acknowledge new orders.
- Update order statuses.
- Manage returns.
- Provide refunds.
Here's a summary of how to use the Orders API:
- Enroll your Merchant Center account in Buy on Google
- This is in addition to your Merchant Center enrollment. Contact us to ensure that your Google accounts are enrolled.
- Agree to the Buy on Google terms
- These are located at Merchant Center > Buy on Google during the onboarding stage or under the About sub-menu.
- Configure a new project
- Download a JSON service account key that you may need to edit as
described in Service account key.
For additional information, see Configure a Google Console Project.
- Assign the Buy on Google Order Manager role
- See Assign Order Manager Role. Add this to the Google Service Account (GSA) that you created in the previous step. Do this for any other accounts that need to 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
- You only need to do this if you're making calls through a web service and not using a library. See Service account key.
- Implement OAuth 2.0 authentication
- See Authorizaing Requests. Alternatively, you can get an access token to include in your RESTful requests, as described in Getting an access token.
- Call the Orders API
- See Using the Orders API for more detail, or this quick tutorial to try the API. Use sandbox mode to test your Orders API implementation before deploying it to production.
Assign the Order Manager role
Before you can use the Orders API, you must assign the Buy on Google Order Manager role to your Google Service Account (GSA) and any other accounts that need access to the Orders API or the Orders view in Merchant Center.
Here's how to assign the Order Manager role:
- Open the Merchant Center.
- Click the wrench icon in the upper right corner and select Account Access:
Merchant Center displays a list of users and their roles.
If you don't see Account Access in the drop-down list, your account doesn't have administrative privileges.
- Click a user's row to edit it.
The User Preferences view displays.
If an account isn't in the user list, click + to add it.
- In the User access section, check the
Order Manager checkbox:
- Click Save to save your changes.
The Buy 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 two modes:
- Sandbox mode
- To build and test your implementation in a sandbox. Sometimes new features are available here first.
- Production mode
- To deploy your implementation in a production environment.
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:
- Sandbox mode (
- For experimenting and issuing test requests, use sandbox mode by specifying
v2.1sandboxfor the mode in your URLs. For example:
Sandbox mode supports the following additional methods that production mode doesn't:
- Production mode (
- Use production mode for live order processing by specifying
v2.1for the mode in your URLs. For example:
Use Try this API
To create a test order with Try this API:
- Open the API Reference >
Note that Try this API calls the method of the page you're currently viewing. For example, if you're viewing the
createtestorderreference page, Try this API 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,
The following example shows a call with Merchant ID
- Click Execute.
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:
- Copy the
orderIdfrom the response. You need this ID for the next steps.
After creating a test order, you can complete the order process and update the order status at each step:
- See the contents of the newly created order with the
- Get a list of all the orders under your account with the
- Advance your order's status to
- Acknowledge the order with
- Optionally assign a Merchant Order ID with
- Create a shipment and change the order status to
- Optionally use
chargeto charge the customer before you ship the order.
- Set shipment's status to
See Using the Orders API for more detail.
Google provides the following order templates:
template1: Two products/skus, quantities of 2 and 1, no promotion
template1a: Two products/skus, quantities of 2 and 1, no promotion
template1b: Two products/skus, quantities of 2 and 1, specific product promotion
template2: One product/sku, quantity of 2, no promotion
template3: One product/sku, quantity of 2, no promotion, pickup point (France only)
You can set a template with the
templateName parameter in the
The Orders API supports sending orders with multiple products/skus in different quantities.
You can see the template's format by calling
gettestordertemplate with your merchant
ID and the name of the template you want to view.