Overview of Merchant Products API

This page explains how you can upload and manage your products programmatically. Using the Merchant Products API, you can insert or update a product in a data source, retrieve a product from your account, and delete a product from a data source.

Merchant Products API contains two resources.

  • productInputs represents the input parts of your products.
  • products represents the processed products that was constructed from your input parts.

productInputs can be primary and supplementary, depending whether it is uploaded to a primary data source or a supplemental data source. Each product will be constructed from a single primary productInput and any number of supplemental productInputs.

You can use the Merchant Products API to create an online or local store catalogs, these are products which can appear on multiple shopping destinations. You can use the productInputs resource once you have created your Merchant Center account, set up your first data source and are ready to upload an initial set of products through the API.

Although merchants have the ability to upload products using a file called a PrimaryProductDataSource, there are several advantages of creating and deleting products using the Merchant API. These advantages include faster response time and the ability to update products in real time, without the need to manage large files. It may take up to several hours for product changes made by API calls to show in the Shopping database.

Prerequisites

If you don't have a data source, create a data source using the Merchant DataSources API or the Merchant Center.

If you already have a data source that you created either using the Merchant Center UI or using the API, then you can use the Merchant Products API to add your products. If you are using the Content API for Shopping to add products, refer to the migration guide to understand how to get started with the Merchant Products API.

You are responsible for complying with the Shopping Ads and free listings policies. Shopping Ads reserves the right to enforce these policies and respond appropriately if we find content or behavior that violates these policies.

Resources

The products resource lets you retrieve product information from the Shopping database.

The productInput resource represents the input data you submit for a product. It also provides methods that let you update, or delete product information one at a time, or many at a time in batch mode. A productInput resource must have the following fields:

  • channel: The channel of the product.
  • offerId: The unique identifier for the product.
  • contentLanguage: The two-letter ISO 639-1 language code for the product.
  • feedLabel: The feed label for the product.

Upload a product input into your account

To upload a product input into your account, use the accounts.productInputs.insert method. You must pass the unique identifier of the primary or supplemental data source.

The following sample request shows how you can use the accounts.productInputs.insert method to upload a product input to your merchant account. The request sets the shipping price and region, and custom attributes like date of manufacture and size.

POST https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource={DATASOURCE}

{
  "name": "{PRODUCT_TITLE}",
  "versionNumber": {VERSION_NUMBER},
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "offerId": "{OFFER_ID}",
  "channel": "ONLINE",
  "attributes": {
    "availability": "in stock",
    "imageLink": "{IMAGE_LINK}",
    "link": "{PRODUCT_LINK}",
    "brand": "{BRAND_NAME}",
    "price": {
      "currencyCode": "{CURRENCY_CODE}",
      "amountMicros": {PRICE}
    },
    "color": "red",
    "productWeight": {
      "value": 320,
      "unit": "g"
    },
    "adult": false,
    "shipping": [
      {
        "country": "GB",
        "price": {
          "amountMicros": {SHIPPING_COST},
          "currencyCode": "{CURRENCY_CODE_SHIPPING}"
        },
        "postalCode": "{SHIPPING_POSTALCODE}",
        "service": "",
        "region": "{SHIPPING_REGION}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}"
      }
    ],
    "gender": "Female"
  },
  "customAttributes": [
    {
      "name": "size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

Replace the following:

  • {ACCOUNT_ID}: The unique identifier of your Merchant Center account.
  • {DATASOURCE}: The unique identifier of the data source. It should be in the format accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}.
  • {PRODUCT_TITLE}: The name of the product.
  • {VERSION_NUMBER}: The version number of the product. Optional.
  • {CONTENT_LANGUAGE}: The two-letter ISO 639-1 language code for the product. Required.
  • {FEED_LABEL}: The CLDR territory code for the region where you want to sell the product. If the value provided for feedLabel isn't valid, the targetCountry field isn't populated.
  • {OFFER_ID}: The unique identifier of the product. Required.
  • {IMAGE_LINK}: The link to the product's image on your website. Optional.
  • {PRODUCT_LINK}: The link to the product on your website. Optional.
  • {CURRENCY_CODE}: The currency of the price using three-letter acronyms according to ISO 4217. Optional.
  • {PRICE}: The price of the product represented as a number in micros. Optional.
  • {SHIPPING_COST}: The fixed shipping price represented as a number. Optional.
  • {SHIPPING_POSTALCODE}: The postal code range where the shipping rate applies. Optional.
  • {MAX_HANDLING_TIME}: The maximum handling time in business days between when the order is received and when it is shipped. Optional.
  • {MIN_HANDLING_TIME}: The minimum handling time in business days between when the order is received and when it is shipped. The value 0 means that the order is delivered on the same day as it is received. Optional.
  • {MAX_TRANSIT_TIME}: The maximum transit time in business days between when the order has been shipped and when it is delivered. Optional.
  • {MIN_TRANSIT_TIME}: The minimum transit time in business days between when the order has been shipped and when it is delivered. The value 0 means that the order is delivered on the same day as it is shipped. Optional.

When the request runs successfully, you see the following response:

{
  "name": "{PRODUCT_NAME}",
  "product": "{PRODUCT_ID}",
  "channel": "ONLINE",
  "offerId": "{OFFER_ID}",
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "versionNumber": "{VERSION_NUMBER}",
  "attributes": {
    "link": "{PRODUCT_LINK}",
    "imageLink": "{IMAGE_LINK}",
    "adult": false,
    "availability": "in stock",
    "brand": "{BRAND_NAME}",
    "color": "red",
    "gender": "Female",
    "price": {
      "amountMicros": "{PRICE}",
      "currencyCode": "{CURRENCY_CODE}"
    },
    "shipping": [
      {
        "price": {
          "amountMicros": "{SHIPPING_COST}",
          "currencyCode": "{CURRENCY_CODE}"
        },
        "country": "{SHIPPING_COUNTRY}",
        "region": "{SHIPPING_REGION}",
        "postalCode": "{SHIPPING_POSTALCODE}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}"
      }
    ],
    "productWeight": {
      "value": 320,
      "unit": "g"
    }
  },
  "customAttributes": [
    {
      "name": "Size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

Retrieve a processed product from your account

To retrieve a processed product from your account, use the accounts.products.get method. It can take several minutes for the processed product to appear after insertion.

You can get the resource name of the processed product from the product field in the response of accounts.productInputs.insert

Delete a product input from your account

To delete a product input from your account, use the accounts.productInputs.delete method. You must pass the unique identifier of the primary or supplemental data source that the product belongs to for deleting a product using the Merchant Products API.

List products from your account

To list the processed products in your account, use the accounts.products.list method.