orders resource

The orders resource enables merchants to process orders they receive through Buy on Google.

You can use the orders resource 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 resource:

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.

Caution: Store the key file securely and keep track of its location. If you lose it, you cannot download it again, but you can repeat this step to create a new project and get a new key file.

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 resource 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 resource

See Using the orders resource for more detail, or this quick tutorial to try the resource. Use sandbox mode to test your orders resource implementation before deploying it to production.

Assign the Order Manager role

Before you can use the orders resource, 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 resource 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:

   

   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:

   

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 resource or the Orders view in Merchant Center.

Note: If you don't see the 'Order manager' role option, you need to opt into the Buy on Google program for it to become available.

Sandbox and production modes

You can use the orders resource 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:

• createtestorder
• advancetestorder
• gettestordertemplate

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.

Note: To use Try this API, you must be logged into a Merchant Center account that has the Buy on Google Order Manager role..

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 resource 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 captureOrder to charge the customer before you ship the order.
8. Set shipment's status to delivered with updateshipment.

See Using the orders resource 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 resource 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.