Version v2 of the Content API is scheduled for sunset on September 30th, 2021. Onboarding to v2 ended on April 30, 2021. To avoid disruptions with your integration, please migrate to v2.1 as soon as possible.

For more information, see Migrating to v2.1 and this blog post.

Orders API

The Orders API enables merchants to process orders received through Buy on Google. Through this API, participating merchants can:

  • Receive and acknowledge new orders
  • Reflect their progress shipping them
  • Provide refunds in response to returns or other events

Get started with the Orders API

To use the Orders API:

  1. Enroll your Merchant Center account in "Buy on Google". (This is in addition to your Merchant Center's enrollment.) Please contact us to ensure that your Google accounts are enrolled.

  2. Agree to the Buy on Google terms in your Merchant Center account (located at Merchant Center > Buy on Google during the onboarding stage or under the About sub-menu after you're live).
  3. 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.

  4. Add the "Buy 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.
  5. (Optional) Download the Content API client libraries for your app.
  6. Modify the API key (if you are making calls through a web service and not using a library).
  7. 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.
  8. 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 "Buy 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:

  1. Open the Merchants 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 do not see the Account Access option in the drop-down list, your account does not have administrative privileges.

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

  4. In the User access section, check the Order Manager checkbox, as the following example shows:

    account access

  5. Click the Save button 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 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.1"): For your live order processing, use production mode by specifying "/v2.1" for the mode in your URLs. For example:
    GET ''
  • 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 ''

    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":

  1. Open the API Reference and navigate to the createtestorder page.

    Note that "Try this API" calls the method whose documentation you are currently viewing. For example, if you are viewing the createtestorder reference page, the "Try this API" feature 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 simple call with merchant ID "42":

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

  5. Copy the value of orderId from the response. You can use the order's ID in Next steps.

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:

  1. See the contents of the newly created order with the get method. You can also use list to get a list of all orders.
  2. Advance your order's status to "pendingShipment" with advancetestorder.
  3. Acknowledge the receipt of the order with acknowledge.
  4. Optionally assign a Merchant Order ID with updatemerchantorderid.
  5. Use shiplineitems to create a shipment for your order and change its status to "shipped".
  6. Finish up by setting the shipment's status to "delivered" with updateshipment.

These steps are described in detail in Using the Orders API.

Order templates

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

  • "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)

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.