This guide is for third-party apps and marketplaces that want to display the catalogues of Common Ground shops discovery apps, aggregators, want-list matchers and similar.
It's a read-only, public feed. There are no mutations, no shop Secret Keys, and no per-shop onboarding on your side. A shop opts in once from its admin panel, and from then on its catalogue is available to you as a daily-refreshed JSON file.
Terms of use
Access to this feed is provided as a courtesy and on the following terms:
Display only. The feed exists solely for aggregators to display shop and inventory data to their users. It may not be used for any other purpose.
No tracking or analytics. No trackers, analytics, pixels, fingerprinting or telemetry of any kind may be attached to the feed data, the shop links, or shoppers who reach a store through your app.
No financial arrangement. This is a non-commercial, good-faith integration. There is no revenue share, fee, or financial deal between us, in either direction.
No direct monetisation of shops. You may not use this collaboration — or the shop contact details, names, or data obtained through it — to approach stores directly, sell them services, or otherwise monetise the relationship with them.
Feed access only. Inventory must be read exclusively through the provided feed. Scraping storefronts, the APIs, or any other Common Ground surface is not permitted.
No redistribution or resale. The feed data may not be resold, relicensed, or passed on to third parties.
Attribution and link-back. Each item must link back to the shop's own storefront so traffic is driven to the store.
Respect opt-in and removals. Only display shops that appear in the feed, and remove any shop that drops out of it.
Revocable at any time. Access may be revoked at any time, for any reason, without notice.
How it works
We issue you a partner token.
You call the shop list endpoint to discover every shop that has opted in to a public inventory.
For each shop, you fetch its inventory JSON straight from our CDN.
You re-sync on a daily schedule.
Getting access
Email to request a partner token. We'll send you a bearer token unique to your integration. Keep it private and send it as an Authorization: Bearer <token> header. It only gates the shop-list endpoint — the inventory files themselves are public — so think of it as identifying your integration rather than protecting the data.
Step 1 — List shops with a public inventory
GET https://api-client.common-ground.io/inventory/dumps/listAuthorization: Bearer <YOUR_PARTNER_TOKEN>
Response
id — the shop's numeric id; use it to build the inventory URL (Step 2).
shopName — display name of the shop.
key — S3 key of the inventory file; prefix it with the CDN host for the full URL.
date — when the inventory file was last regenerated; use it to skip unchanged shops.
uri — the shop's primary storefront URL.
logo — shop logo (SVG or raster), if set.
alpha2 — ISO 3166-1 alpha-2 country code of the shop.
geoLoc —
[longitude, latitude]of the shop, if set.pickup — whether the shop offers in-store collection.
toRemove — shops no longer published; drop any of these you've previously indexed.
Step 2 — Fetch a shop's inventory
Take the key from the list response (or build it from the shop id) and prefix it with the CDN host:
GET https://static.common-ground.io/shops/1234/inventory.jsonNo authentication is required for this URL. The file is cached for ~1 hour and carries a Last-Modified header — honour it with If-Modified-Since to avoid re-downloading unchanged catalogues.
Inventory shape
The file is a JSON array of items. Each item has a type (e.g. ReleaseItem, ProductItem, BookItem), shared fields, an array of listings (the sellable variants), and a data block whose fields depend on the item type.
Shared fields
type — item type:
ReleaseItem,ProductItem,BookItem, …id — stable numeric item id within the shop.
path — path to the item on the storefront; append it to the shop's
uri.descriptions.main — catalogue description of the item.
descriptions.shop.text — the shop's own note about this specific copy.
Listings (sellable variants) — only published listings with stock are included.
id — stable listing id; treat this as the SKU for syncing.
status — always
publishedin the feed.stock.quantity — units in stock;
nullmeans stock isn't tracked (treat as available).prices.sale — selling price.
prices.beforeTaxes — price excluding taxes.
prices.compare — original/compare-at price if discounted.
secondHand —
truefor used stock.options — variant attributes; for second-hand records this carries media/sleeve condition.
data — release fields (ReleaseItem)
title — release title.
artists — array of artist names.
labels — array of record labels.
discogsId — Discogs release id. Use this to dedupe against your Discogs catalogue.
formats — format descriptors (e.g.
["Vinyl", "LP", "Album"]).genres / styles — Discogs-style genres and styles.
year — release year.
country — release country.
weight — item weight in grams.
images — artwork image URLs.
Product and book items use the same envelope with a different data block (manufacturer, categories for products; authors, publisher, language, pageCount for books). Filter on type if you only want records.
A shop's feed is a single file capped at 50,000 items — there's no pagination to handle.
Syncing best practices
Daily is enough — files regenerate roughly daily.
Use
dateandLast-Modifiedto skip shops whose catalogue hasn't changed since your last run.Honour
toRemove— delete those shops from your index.Key on
listing.idfor per-variant tracking anditem.idfor the parent item.
Rules of the road
This feed is the only supported way to read shop catalogues in bulk. Please don't scrape the storefronts directly — they're rate-limited and may be blocked.
Link back to the shop using its
uri+ the itempathso you drive traffic to the store.If you'd like to display the Common Ground brand or need an SVG logo, get in touch.
Contact
Questions, a pilot token, or interest in a deeper integration: .