Inventory source file for Partners

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 source, open to partners with a token. There is 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 source file 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 with a public inventory.

• For each shop, you download its inventory from the url the list gives you, with the same token.

• You re-sync on a daily schedule.

Getting access
Email support@common-ground.io to request a partner token. We’ll send you a token unique to your integration. Keep it private and send it as an Authorization: Bearer <token> header on every request, both for the shop list and for each inventory. We can replace or revoke it at any time.

List shops with a public inventory

GET https://api-client.common-ground.io/inventory/dumps/list

Authorization: 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.

• url — where to download the shop’s inventory, on the shop’s own domain. Send your token with it.

• date — when the inventory file was last regenerated; use it to skip unchanged shops.

• uri — the shop’s storefront: its own domain, or its Common Ground address if it has none.

• 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.

Fetch a shop’s inventory

Download the url from the list response, with your token:

GET https://www.example-shop.com/inventory/json
Authorization: Bearer <YOUR_PARTNER_TOKEN>

Without a valid token the request is refused. Partner requests are not rate-limited, so you can fetch one shop after another.

Each response carries a Last-Modified header. Send it back as If-Modified-Since on your next sync: if the inventory hasn’t changed since, you get a 304 Not Modified with no body, and you can keep the copy you already have.

Syncing best practices. Replace the second bullet with:

• Use date from the list to skip shops whose inventory hasn’t changed, or send If-Modified-Since with the Last-Modified of your last download and keep your copy on a 304.

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 published in the feed.

• stock.quantity — units in stock; null means 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 — true for 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 date and Last-Modified to skip shops whose catalogue hasn't changed since your last run.

• Honour toRemove — delete those shops from your index.

• Key on listing.id for per-variant tracking and item.id for 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 url + the item path so 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: support@common-ground.io.