Orders API

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.

Get started

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:

  1. Open the Merchant Center.
  2. Click the wrench icon in the upper right corner and select Account Access:

    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.

  3. 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.

  4. In the User access section, check the Order Manager checkbox:

    account access

  5. 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:

https://www.googleapis.com/content/mode/merchant_ID/orders/

Where merchant_ID is your Merchant Center ID, and mode specifies which mode to use:

Sandbox mode (v2.1sandbox)
For experimenting and issuing test requests, use sandbox mode by specifying v2.1sandbox for the mode in your URLs. For example:
      GET 'https://www.googleapis.com/content/v2.1sandbox/42/orders/'
      

Sandbox mode supports the following additional methods that production mode doesn't:

Production mode (v2.1)
Use production mode for live order processing by specifying v2.1 for the mode in your URLs. For example:
 GET 'https://www.googleapis.com/content/v2.1/42/orders/'
      

Use Try this API

To create test orders in sandbox mode, use the Try this API box on the right side of the createtestorder page. Try the API works on all the API documentation pages.

To create a test order with Try this API:

  1. Open the API Reference > createtestorder page.

    Note that Try this API calls the method of the page you're currently viewing. For example, if you're viewing the createtestorder reference page, Try this API calls createtestorder. To call get, navigate to the get reference page.

  2. Enter your merchant ID in the merchantId request parameter field.
  3. Add the templateName field to the request body, and set it to one of the templates described below; for example, template1.

    The following example shows a call with Merchant ID 42:

  4. 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:

  5. Copy the orderId from the response. You need this ID for the next steps.

Next steps

After creating a test order, you can complete the order process and update the order status at each step:

  1. See the contents of the newly created order with the get method.
  2. Get a list of all the orders under your account with the list method.
  3. Advance your order's status to pendingShipment with advancetestorder.
  4. Acknowledge the order with acknowledge.
  5. Optionally assign a Merchant Order ID with updatemerchantorderid.
  6. Create a shipment and change the order status to shipped with shiplineitems.
  7. Optionally use charge to charge the customer before you ship the order.
  8. Set shipment's status to delivered with updateshipment.

See Using the Orders API for more detail.

Order templates

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 createtestorder method.

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.