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:
- Merchants or integration partners that need a programmatic solution for adding return policies/addresses.
- 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://www.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://www.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://www.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://www.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://www.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://www.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://www.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://www.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.