Buy on Google for Search and Shopping will no longer be available starting September 26, 2023. You can retrieve existing orders until October 31, 2024. See Get started with Buy on Google for details.

Buy on Google return settings

You need to set a returnaddress and returnpolicy for each product you sell on Buy on Google.

You should set the following attributes for each return policy:

Return window: Set in the policy section (called the general policy).
Non-free return reasons: You can use non-free return reasons to charge the customer for returning a purchase outside your free return policy, for example betterPriceFound, changedMind, doesNotFit, noLongerNeeded, or orderedWrongItem.
Seasonal overrides: Seasonal overrides modify a return policy at certain times during the year. For example, you might have a holiday season policy to accept returns for longer than you normally would.You can have multiple seasonal overrides per return policy.

Return addresses

Any returnable product must have a return address set. You can use the label attribute to name a return address and apply it to multiple products. The default return address for your products is the address for your Merchant Center account.

A returnaddress has the following structure:

{
  "returnAddressId": string,
  "label": string,
  "country": string,
  "address": {
    "recipientName": string,
    "streetAddress": [
      string
    ],
    "locality": string,
    "region": string,
    "postalCode": string,
    "country": string
  }
  "phoneNumber": string,
  "kind": string
}

You can use the following methods to create, view, update, or delete a returnaddress.

list

You can use returnaddress.list to list your existing return addresses.

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/returnaddress

Here's a sample response:

{
  "kind": "content#returnaddressListResponse",
  "resources": [
    {
      "kind": "content#returnAddress",
      "country": "US",
      "returnAddressId": "US:default",
      "label": "default",
      "phoneNumber": "+1 123-456-7890",
      "address": {
        "locality": "Sacramento",
        "country": "",
        "region": "ca",
        "streetAddress": [
          "2500 Arden Way",
          ""
        ],
        "postalCode": "95825-2414",
        "recipientName": "Ariel Cruz"
      }
    },
    {
      "kind": "content#returnAddress",
      "country": "US",
      "returnAddressId": "US:test",
      "label": "test",
      "phoneNumber": "+1 222-333-4444",
      "address": {
        "locality": "MOUNTAIN VIEW",
        "country": "US",
        "region": "CA",
        "streetAddress": [
          "1600 AMPHITHEATRE PKWY"
        ],
        "postalCode": "94043-1351",
        "recipientName": "Yuri Lee"
      }
    }
  ]
}

returnAddressId refers to an existing return address. The returnAddressIdis generated by Google, in the format country:label. You can find the returnAddressId in the response from an insert or list call. You need the returnAddressId to call the delete and get methods.

insert

You can use returnaddress.insert to add a new address or change an existing address. Calls to insert will modify all existing addresses with the label you provide in the request. If the label you provide doesn't exist yet, it's added when you make the call. insert verifies the address and returns a 400 code if the address is invalid. Otherwise, insert returns the updated return address.

POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/returnaddress

Here's a sample request:

{
  "label": "test",
  "country": "US",
  "address": {
    "locality": "MOUNTAIN VIEW",
    "postalCode": "94043-1351",
    "recipientName": "Yuri Lee",
    "region": "CA",
    "streetAddress": [
      "1600 AMPHITHEATRE PKWY"
    ],
    "country": "US"
  },
  "phoneNumber": "+1 222-333-4444"
}

Here's a sample response:

{
  "kind": "content#returnAddress",
  "country": "US",
  "returnAddressId": "US:test",
  "label": "test",
  "phoneNumber": "+1 222-333-4444",
  "address": {
    "locality": "MOUNTAIN VIEW",
    "country": "US",
    "region": "CA",
    "streetAddress": [
      "1600 AMPHITHEATRE PKWY"
    ],
    "postalCode": "94043-1351",
    "recipientName": "Yuri Lee"
  }
}

get

You can use returnaddress.get to get a specific return address by returnAddressId.

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/returnaddress/returnAddressId

Here's a sample response:

{
  "kind": "content#returnAddress",
  "country": "US",
  "returnAddressId": "US:test",
  "label": "test",
  "phoneNumber": "+1 222-333-4444",
  "address": {
    "locality": "MOUNTAIN VIEW",
    "country": "US",
    "region": "CA",
    "streetAddress": [
      "1600 AMPHITHEATRE PKWY"
    ],
    "postalCode": "94043-1351",
    "recipientName": "Yuri Lee"
  }
}

delete

You can use returnaddress.delete to delete an existing return address by returnAddressId. After deleting the return address, this method returns a 204 No Content code.

DELETE https://shoppingcontent.googleapis.com/content/v2.1/merchantId/returnaddress/returnAddressId

Return policies

Return policies help you automate returns by storing information like return windows, non-free return reasons, and seasonal overrides. You automatically have a default return policy for your Merchant Center account, and you can use this resource to manage additional return policies.

A returnpolicy has the following structure:

{
  "returnPolicyId": string,
  "label": string,
  "country": string,
  "name": string,
  "policy": {
    "type": string,
    "numberOfDays": string,
    "lastReturnDate": string
  },
  "seasonalOverrides": [
    {
      "name": string,
      "startDate": string,
      "endDate": string,
      "policy": {
        "type": string,
        "numberOfDays": string,
        "lastReturnDate": string
      },
    }
  ],
  "nonFreeReturnReasons": [
    string
  ],
  "kind": string,
  "returnShippingFee": {
    "value": string,
    "currency": string
  }
}

Accepted values for type include lifetimeReturns, noReturns, and numberOfDaysAfterDelivery. If the value is numberOfDaysAfterDelivery, then numberOfDays must have a value of 14, 15, 21, 28, 30, 45, 60, 90, 100, 180 , 270, or 365. The default policy can be no less than 30 days. Depending on the type of product, other restrictions may apply.

You can use the following methods to modify a returnpolicy.

list

You can use returnpolicy.list to list all existing return policies.

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/returnpolicy

Here's a sample request:

{
  "kind": "content#returnpolicyListResponse",
  "resources": [
    {
      "nonFreeReturnReasons": [
        "betterPriceFound"
      ],
      "kind": "content#returnPolicy",
      "name": "",
      "country": "US",
      "seasonalOverrides": [
        {
          "policy": {
            "type": "lifetimeReturns"
          },
          "startDate": "2019-11-01",
          "endDate": "2020-01-01",
          "name": "Holiday"
        }
      ],
      "label": "default",
      "policy": {
        "numberOfDays": "30",
        "type": "numberOfDaysAfterDelivery"
      },
      "returnPolicyId": "transactions:US:default"
    }
  ]
}

returnPolicyId refers to an existing return policy. returnPolicyId is a string formed from the label and country attributes, in the format transactions:country:label. You can find the returnPolicyId in the response from an insert or list call. You need the returnAddressId to call the delete and get methods.

insert

You can use returnpolicy.insert to create a new return policy, or to modify an existing policy. The label, country, name, and policy fields are required. If nonFreeReturnReasons is specified, returnShippingFee is also required.

POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/returnpolicy

Here's a sample request:

{
  "name": "30days",
  "label": "30days",
  "country": "US",
  "policy": {
    "type": "numberOfDaysAfterDelivery",
    "numberOfDays": "30"
  },
  "nonFreeReturnReasons": [
    "betterPriceFound"
  ],
  "returnShippingFee": {
    "currency": "USD",
    "value": "5.00"
  },
  "seasonalOverrides": [
    {
      "name": "holiday",
      "policy": {
        "type": "lastReturnDate",
        "lastReturnDate": "2022-02-15"
      },
      "startDate": "2021-11-01",
      "endDate": "2022-01-15"
    }
  ]
}

Here's a sample response:

{
  "kind": "content#returnPolicy",
  "returnPolicyId": "transactions:US:30days",
  "label": "30days",
  "country": "US",
  "name": "30days",
  "policy": {
    "type": "numberOfDaysAfterDelivery",
    "numberOfDays": "30"
  },
  "seasonalOverrides": [
    {
      "name": "holiday",
      "startDate": "2021-11-01",
      "endDate": "2022-01-15",
      "policy": {
        "type": "lastReturnDate",
        "lastReturnDate": "2022-02-15"
      }
    }
  ],
  "nonFreeReturnReasons": [
    "betterPriceFound"
  ],
  "returnShippingFee": {
    "value": "5.00",
    "currency": "USD"
  }
}

get

You can use returnpolicy.get to get a specific return policy by returnPolicyId.

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/returnpolicy/returnPolicyId

Here's a sample response:

{
  "nonFreeReturnReasons": [
    "betterPriceFound"
  ],
  "kind": "content#returnPolicy",
  "name": "",
  "country": "US",
  "seasonalOverrides": [
    {
      "policy": {
        "type": "lifetimeReturns"
      },
      "startDate": "2019-11-01",
      "endDate": "2020-01-01",
      "name": "Holiday"
    }
  ],
  "label": "default",
  "policy": {
    "numberOfDays": "30",
    "type": "numberOfDaysAfterDelivery"
  },
  "returnPolicyId": "transactions:US:default"
}

delete

You can use returnpolicy.delete to delete an existing return policy by returnPolicyId. After deleting the return policy, this method returns a 204 No Content code.

DELETE https://shoppingcontent.googleapis.com/content/v2.1/merchantId/returnpolicy/returnPolicyId

custombatch

You can use returnpolicy.custombatch to combine multiple return policy related calls into a single request by specifying the method, for example get, insert, or delete. The request body contains an instance of ReturnpolicyCustomBatchRequest.

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/returnpolicy/batch

Here's a sample request:

{
  "entries": [
    {
      "batchId": "1",
      "method": "get",
      "returnPolicyId": "9876543",
      "merchantId": "1234567"
    }
  ]
}

Here's a sample response:

{
  "kind": "content#returnpolicyCustomBatchResponse",
  "entries": [
    {
      "kind": "content#returnpolicyCustomBatchResponseEntry",
      "batchId": "1",
      "errors": {
        "errors": [
          {
            "domain": "global",
            "reason": "invalid",
            "message": "[item id] Invalid item id: 2883698234"
          }
        ],
        "code": "400",
        "message": "[item id] Invalid item id: 2883698234"
      }
    }
  ]
}

Overview

Shopping Ads & free listings