Orders API

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:

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

  2. Agree to the Purchases on Google terms in your Merchant Center account (check the checkbox at Merchant Center > Purchases on Google > Settings).
  3. Configure a Google Console Project:

    1. Create a new project (if one doesn't already exist).
    2. Enable the Content API for Shopping for the project.
    3. Create a Google Service Account (GSA).
    4. Download the key as a JSON file. You may need to edit this file, as described in Service account key.
  4. Add the new GSA to your Merchant Center account. Be sure that you:

    1. Use the correct email address for the GSA (it ends in "@developer.gserviceaccount.com").
    2. Add the "Purchases on Google Order Manager" role to the GSA, as described in Assign the order manager role.

    Repeat this step for all accounts that will use the Orders API or access the Orders view in the 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 "Purchases on Google Order Manager" to your GSA and any other accounts that will access the Orders API or the Orders view in the Merchant Center.

To assign the order manager role:

  1. Open the Merchants Center.
  2. Click the 3 dots in the upper right and select Users:

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

  3. Click a user's row to edit it. The User Preferences view displays.

    If your GSA is not in the user list, click the + icon to add it.

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

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

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 envirionment. Sandbox mode might also be where new API features can first be used.

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:

  • Production mode: For your live order processing, use production mode by specifying "/v2" for the mode in your URLs. For example:
    GET 'https://www.googleapis.com/content/v2/42/orders/'
    
  • Sandbox mode: For experimenting and issuing test requests, use sandbox mode by specifying "/v2sandbox" for the mode in your URLs. For example:
    GET 'https://www.googleapis.com/content/v2sandbox/42/orders/'
    

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

发送以下问题的反馈:

此网页
Content API for Shopping