Version v2 of the Content API is scheduled for sunset on September 30th, 2021. Onboarding to v2 will stop 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.

Return Settings API

This guide covers the purpose, use cases, and methodologies of the Return Settings API. This API allows you to set up your return policies and return addresses without using Merchant Center.

For each product that you sell on Buy on Google, you will need to set addresses to which customers can return products and identify the policies under which they can return the product. To do that, you can use these two resources: Returnaddress and Returnpolicy. The return policies may contain seasonal overrides which allow you to change your policies at certain times of year. For example, the holiday season.

The Returnaddress and Returnpolicy documentation provides more detail about the methods and attributes in these resources.

Purpose of API

The API is particularly useful for:

  1. Merchants or integration partners that need a programmatic solution for adding return policies/addresses.
  2. Merchants with a lot of return policies or return addresses to manage.

Return addresses

When a product is returned, it needs a return address. You can use Returnaddress to provide return addresses. You can add labels to your addresses so that they can be applied to products using the return_address_label attribute. The label for the default address (the first one you entered into the Merchant Center when you set up your merchant account) is "default".

The Returnaddress.insert method checks the addresses you send to confirm that they are real-world addresses. A bad address results in a 400 response code with a message of [address] Invalid address.

Invalid address response body

{
  "error": {
    "code": 400,
    "message": "[address] Invalid address.",
    "errors": [
      {
        "domain": "global",
        "message": "[address] Invalid address.",
        "reason": "invalid"
      }
    ]
  }
}

The returnAddressId is used to reference an existing address in other calls to the API. The returnAddressId is a string formed from the label and the country attributes like this: country:label. When you make a Returnaddress.insert or Returnaddress.list call, the returnAddressId is in the response. You need to use the returnAddressId when calling the Returnaddress.delete or Returnaddress.get method to specify which return address you want to affect.

Return policy

You will want to set a return policy for your products. You already have a default return policy (which has a label of "default"), but you can also have other policies. This API can be used to add and change both the default and any other policies you have. You can then use the return_policy_label to assign these to offers.

There are three other policy choices that you will need to set: the return window in the policy section (called the "general policy"), nonFreeReturnReasons, and seasonalOverrides (discussed in the next section).

Example general policy from Returnpolicy request

...
      "policy": {
        "numberOfDays": "30",
        "type": "numberOfDaysAfterDelivery"
      }
...

Policy has multiple components: type, lastReturnDate, and numberOfDays.

Accepted values for type include lifetimeReturns, noReturns, and numberOfDaysAfterDelivery. If the value is numberOfDaysAfterDelivery then numberOfDays must have a value of the number of days after delivery that the order will be eligible for return.

The numberOfDaysAfterDelivery field can have only certain discrete values which include 14, 15, 21, 28, 30, 45, 60, 90, 100, 180, 270, and 365 (for the default policy, only values greater than 30 can be used). Depending on the type of product, other restrictions may apply (for most items a minimum of 30 days is required for returns).

NonFreeReturnReasons allows you to charge the customer for buyer remorse returns which are betterPriceFound, changedMind, doesNotFit, noLongerNeeded, and orderedWrongItem. You can set multiple reasons and if the customer selects one of the reasons set in the policy when they initiate a return, the customer will need to pay for the return. If the customer selects a different reason, you'll have to pay for the return.

Seasonal overrides

Seasonal overrides are added to a return policy to allow you to override the policy at certain times during the year. For example, you might have a holiday season policy that allows people to return things for longer than you normally would.

You can have multiple seasonal overrides in a return policy. Each seasonal override policy, needs a name, a startDate, an endDate, and a policy (called the "override policy") which includes a type and either a lastReturnDate or numberOfDays depending on the type of policy you select. The type field is either lastReturnDate (which needs a lastReturnDate value), numberOfDaysAfterDelivery (which needs a numberOfDays value), noReturns, or lifetimeReturns (the last two do not require any other field).

Policy Type Value Field Required
lastReturnDate lastReturnDate
numberOfDaysAfterDelivery numberOfDays
noReturns None
lifetimeReturns None

Return addresses

List return addresses

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

Example request body for Returnaddress.list

{
  "kind": "content#returnaddressListResponse",
  "resources": [
    {
      "kind": "content#returnAddress",
      "country": "US",
      "returnAddressId": "US:default",
      "label": "default",
      "phoneNumber": "+1 408-456-7890",
      "address": {
        "locality": "Sacramento",
        "country": "",
        "region": "ca",
        "streetAddress": [
          "2500 Arden Way",
          ""
        ],
        "postalCode": "95825-2414",
        "recipientName": "Ariel Fishtail"
      }
    },
    {
      "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": "Mario Brothers"
      }
    }
  ]
}

Insert return address

The insert method can be used to add a new address or change an existing address. If the label in the body is found in among the existing addresses it will be replaced. If the label is not found it will be added.

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

Example request body for Returnaddress.insert

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

Example response body for Returnaddress.insert

{
  "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": "Mario Brothers"
  }
}

Get return address

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

Example response body for Returnaddress.get

{
  "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": "Mario Brothers"
  }
}

Delete return address

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

This returns no body. It returns a 204 No Content response code which means that the delete was successful.

Return policies

List return policies

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

Example request body for Returnpolicy.list

{
  "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"
    }
  ]
}

Get return policy

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

Example response body for Returnpolicy.get

{
  "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"
}

Insert return policy

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

Example request body for Returnpolicy.insert

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

Example response body for Returnpolicy.insert

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

Delete Return Policy

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

This returns no body. It returns a 204 No Content response code which means that the delete was successful.