Feed format
Content API for Shopping
Content API
The Content API for Shopping is not a file format but the alternative to one: instead of publishing a feed Google fetches on a schedule, your system sends individual products to Merchant Center as JSON over HTTP. It is the only way to update Google between scheduled fetches.
Specification
- Content type
- application/json
- Compression
- Not applicable. Requests are individual HTTP calls, optionally batched.
- One product is
- One product is one JSON resource sent in an HTTP request, using camelCase field names rather than the underscore names of a file feed, and with price expressed as an object of value and currency rather than a single string.
- Escaping
- Standard JSON rules apply. The substantive difference from a file feed is that field names and some value formats change: imageLink rather than image_link, itemGroupId rather than item_group_id, and "in stock" with a space where a text feed uses in_stock.
A valid content api
Two products, every required attribute, nothing omitted for brevity. Copy it and replace the values.
POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products
Content-Type: application/json
{
"offerId": "SHIRT-BLK-M",
"title": "Northbound Oxford Shirt, Black, Medium",
"description": "A long-sleeved Oxford shirt in 100% brushed cotton.",
"link": "https://example.com/products/oxford-shirt?variant=101",
"imageLink": "https://cdn.example.com/oxford-black.jpg",
"contentLanguage": "en",
"targetCountry": "GB",
"channel": "online",
"availability": "in stock",
"condition": "new",
"price": { "value": "49.00", "currency": "GBP" },
"brand": "Northbound",
"gtin": "05012345678900",
"itemGroupId": "SHIRT-OXFORD"
}Which channels accept it
| Channel | Support | Notes |
|---|---|---|
| Google Shopping | Supported | The programmatic route into Merchant Center, and the only way to update between scheduled fetches. |
| Meta | Not supported | Meta has its own equivalent in the Catalog Batch API, which is a different interface with different field names. |
| Microsoft Advertising | Not supported | Microsoft fetches a file or imports a Google Merchant Center account. |
| Not supported | Pinterest fetches a scheduled data source. | |
| OpenAI | Not supported | OpenAI expects full catalogue snapshots pushed over SFTP. |
What breaks a content api
The field names are not the feed field names
A file feed uses image_link, item_group_id and google_product_category. The API uses imageLink, itemGroupId and googleProductCategory, and price is an object rather than an amount-plus-currency string. A mapping built for a file needs translating, not copying.
Products expire whether you push or not
An item inserted through the API still has a lifetime and has to be re-sent before it expires. A system that pushes changes only when something changes will watch a stable catalogue disappear item by item, which is a failure mode a scheduled file feed does not have.
Quota is a design constraint
Calls are limited, so a naive implementation that pushes every product on every catalogue change exhausts the quota on a large store. Batching and sending only genuine differences are part of the design rather than optimisations to add later.
It replaces a feed you can look at
When a file feed is wrong you open it. When an API integration is wrong you have to reconstruct what you sent from your own logs. Keeping a generated file alongside the API pushes, even if nothing fetches it, makes the difference between an hour of debugging and a day.
Frequently asked questions
What is the Content API for Shopping?
Google's programmatic interface to Merchant Center. Instead of publishing a feed file that Google fetches on a schedule, your system sends individual products as JSON over HTTP, which is the only way to update between fetches.
Do I need the Content API, or is a feed file enough?
A file is enough for most stores, because a daily fetch keeps a catalogue current if it is regenerated beforehand. The API earns its complexity when price or stock has to be corrected within minutes rather than by the next fetch.
Are the Content API field names the same as the feed attributes?
No. The API uses camelCase, so imageLink and itemGroupId, and price is an object of value and currency rather than a single string. Some enumerated values differ too, such as "in stock" with a space.
Do products pushed through the API still expire?
Yes. They have the same lifetime as items submitted in a file, so they have to be re-sent before it runs out. A push-on-change integration alone will slowly empty a catalogue that is not changing.
Errors this format causes
- Mismatched value: price The price mismatch error means the price in the feed does not agree with the price the channel found when it crawled the landing page. On Shopify the three usual culprits are a feed that has not regenerated since a price change, a link pointing at the wrong market's storefront, and a tax convention difference between the feed and the displayed price.
- Mismatched value: availability The availability mismatch error means the feed says an item is purchasable but the crawled landing page suggests otherwise, or the reverse. On Shopify it is usually a stale feed after a sell-out, or an availability value derived from inventory quantity alone without accounting for variants that do not track inventory or that allow overselling.
Related concepts
- Feed scheduling Feed scheduling is the arrangement where a sales channel fetches a feed from a fixed URL on a repeating timetable instead of the merchant uploading a file. It matters because the interval between regenerations is the window in which a channel can be wrong about a price or a stock level, and most mismatch disapprovals are caused by that window being too wide rather than by a bad mapping.
- Product feed A product feed is a structured file listing every item a shop sells, with one row per purchasable item and one column per attribute the destination understands. Sales channels use it to build their own copy of a catalogue, which is why a feed is a translation of a shop's data into another system's schema rather than an export of it.
Primary sources
Channel specifications change. These are the official documents this page is based on.