Overview of shipping settings

The ShippingSettings resource lets you retrieve and update the shipping settings of your account.

Note: The shippingsettings resource doesn't work for shipping settings created through account-linking or by manual upload of order tracking history. Those shipping settings won't be returned, modified, or deleted by calls to this endpoint.

Google can update the estimated delivery time for some products automatically. For more information, see Enable automatic improvements.

Read, write, or update shipping settings

To use the Merchant API shipping service, do the following:

1. Make a GET request to retrieve the complete shipping settings of your account.
2. Modify the shipping settings.
3. Make an INSERT request with the modified shipping settings.

Etag

Etag is an encoded token to avoid asynchronous updates. The etag changes when any of the shipping settings data changes. Users need to copy the etag they obtained from the GET request to the INSERT request body.

If the shipping settings data changes between the GET request and the INSERT request, you receive an error message requesting another GET request to retrieve the most recent etag token. You need to call GET request to retrieve the new etag token and copy the new etag token to the INSERT request body.

Add your shipping settings

Use shippingsettings.insert to add or update the shipping settings for your account. Here's a sample request that updates the maxTransitDays to 7 for a Shipping Service called GSA Shipping - Free Ship Over $49.99, under account 10.

POST https://merchantapi.googleapis.com/accounts/v1beta/accounts/{accountId}/shippingSettings/

{
  "services": [
    {
      "name": "FedEx",
      "active": true,
      "deliveryCountries": ["US"],
      "currencyCode": "USD",
      "deliveryTime": {
        "minTransitDays": 4,
        "maxTransitDays": 6,
        "minHandlingDays": 0,
        "maxHandlingDays": 0
      },
      "rateGroups": [
        {
          "singleValue": {
            "flatRate": {
              "amountMicros": 5990000,
              "currencyCode": "USD"
            }
          },
          "name": "All products"
        }
      ]
    },
    {
      "name": "GSA Shipping - Free Ship Over $49.99",
      "active": true,
      "deliveryCountries": "US",
      "currencyCode": "USD",
      "deliveryTime": {
        "minTransitDays": 3,
        "maxTransitDays": 7,
        "minHandlingDays": 1,
        "maxHandlingDays": 2
      },
      "rateGroups": [
        {
          "mainTable": {
            "rowHeaders": {
              "prices": [
                {
                  "amountMicros": 49990000,
                  "currencyCode": "USD"
                },
                {
                  "amountMicros": -1,
                  "currencyCode": "USD"
                }
              ]
            },
            "rows": [
              {
                "cells": [
                  {
                    "flatRate": {
                      "amountMicros": 6990000,
                      "currencyCode": "USD"
                    }
                  }
                ]
              },
              {
                "cells": [
                  {
                    "flatRate": {
                      "amountMicros": 0,
                      "currencyCode": "USD"
                    }
                  }
                ]
              }
            ]
          },
          "name": "Free Ship Over $49.99"
        }
      ]
    }
  ]
}

Important: The INSERT request body should contain the full resource body of the shippingsettings resource even if you are just updating a single attribute, as any NULL or missing values in the request body results in the existing values to be nulled.

Set warehouses

The following JSON sample shows how you can use the Merchant Shipping settings service to manage warehouse information for your merchant account:

"warehouses": [
  {
    "name": "warehouse 1",
    "shippingAddress": {
      "streetAddress": {street_address},
      "city": {city},
      "administrativeArea": {administrative_area},
      "postalCode": {postal_code},
      "regionCode": {region_code}
    },
    "cutoffTime": {
      "minutes": {minutes}
    },
    "handlingDays": {handling_days},
    "businessDaysConfig": {
      "businessDays": [
        "MONDAY", "SUNDAY"
      ]
    }
  }
]

Replace the following:

• {street_address}: Street-level part of the warehouse's address.
• {city}: City, town, or commune where the warehouse is located.
• {administrative_area}: The administrative subdivision of the country. For example, a state.
• {postal_code}: The postal code or ZIP code.
• {region_code}: The country code in string.
• {minutes}: Minutes part of the cutoff time until which an order must be placed to be processed in the same day by the warehouse.
• {handling_days}: The number of days it takes for this warehouse to pack and ship an item.

The warehouses resource is a list of warehouses. Each warehouse can be referred by shipping service's warehouse-based delivery time through warehouse.name.

Manage your warehouses

Here's how to use the Merchant API to manage your warehouses:

1. Make a GET request to retrieve all your existing shippingsettings and warehouses.

2. Copy the shippingsettings from the GET request to the UPDATE request.

   Note: If you don't copy all the existing shippingsettings, they are deleted from your account in the INSERT request.

3. Populate the warehouses if you want to use them in the warehouses section for the INSERT request.

4. Make an UPDATE request that contains shippingsettings and warehouses resources.

Here's a sample INSERT request body with warehouse for Warehouse 1 updated from New York to Mountain View:

{
  "services": [
    {
      "name": "Standard Shipping",
      "active": true,
      "deliveryCountries": ["US", "UK"],
      "currencyCode": "USD",
      "deliveryTime": {
        "minHandlingDays": 0,
        "maxHandlingDays": 1,
        "warehouseBasedDeliveryTimes": [
{"carrier": "Fedex"
 "carrierService": "ground"
 "warehouse": "Warehouse 1"
},
{"carrier": "Fedex"
 "carrierService": "2 days"
 "warehouse": "Warehouse 2"
}
]
      },
      "rateGroups": [
        {
          "singleValue": {
            "flatRate": {
              "amountMicros": 0,
              "currencyCode": "USD"
            }
          },
          "name": "Standard Shipping"
        }
      ],
    },
    {
      "name": "Expedited",
            "flatRate": {
              "amountMicros": 9990000,
              "currencyCode": "USD"
            }
          },
          "name": "Expedited"
        }
      ],
    }
  ],
  "warehouses": [
    {
      "name": "Warehouse1",
      "shippingAddress": [
        {
        "streetAddress": "1111 shoreline street"
          "city": "Mountain View",
          "administrativeArea": "CA"
        }
      ]
    },
    {
      "name": "Warehouse 2",
      "country": "US",
      "postalCodeRanges": [
        {
        "streetAddress": "1111 5th avenue"
          "city": "New York",
          "administrativeArea": "NY"
        }
      ]
    }
  ]
}

Add same day delivery

You can use the Content API for Shopping to configure same day delivery shipping services if you have local inventory. Same day delivery shipping services have local_delivery as their shipment_type. All local_delivery shipping services are considered same day deliveries at this time.

You can't change the delivery_time information for local deliveries. Use shippingsettings.insert to set up same day delivery for your local inventory products.

Here's a sample request body that adds a same day delivery service to all stores for your account:

{
  "name": "accounts/accountId/shippingSettings",
  "services": [
    {
      "name": "Local Delivery",
      "active": true,
      "shipmentType": "local_delivery",
      "deliveryCountries": "US",
      "currencyCode": "USD",
      "rateGroups": [
        {
          "singleValue": {
            "flatRate": {
              "amountMicros": 0,
              "currencyCode": "USD"
            }
          }
        }
      ],
      "storeConfig": {
        "storeServiceType": "all stores",
        "storeCodes": [],
        "cutoffConfig": {
          "storeCloseOffsetHours": 2,
          "noDeliveryPostCutoff": true
        },
        "serviceRadius": {
          "value": 4,
          "unit": "Miles"
        }
      }
    }
  ]
}

Add next day delivery

Orders placed after your same day delivery cutoff time are scheduled for next day delivery by default. To turn off next day delivery, set the no_delivery_post_cutoff field to true. If you turn off next day delivery, your shipping services are only visible before the cutoff time each day.

Next day delivery is available only when the shipment_type is local_delivery.

Learn more

To learn about migrating from Content API for Shopping, see Migrate shipping settings management.