Build a marketplace

A listing page

Same shape as the product page recipe, with the commerce parts added: sellers, prices and a counted link.

1. 1Resolve once, store the idYour SKU carries a catalog id. Resolve when the SKU is created, not when a shopper loads the page.
2. 2Read the record and the media togetherSpecifications, silhouette and photographs are independent calls, so they go in parallel.
3. 3Ask for offers in the shopper regionSellers who do not ship there are noise, and a listing nobody refreshed in thirty days is hidden for you.
4. 4Link out through the counted redirectThe outbound link is what proves a placement worked, and it is the only link a seller can measure.
5. 5Cache the assembled pageOne cached page per record, invalidated on version, rather than four calls per view.

1// A listing page, assembled from the catalog.2const [firearm, media, offers] = await Promise.all([3  gunspec.firearms.get(id),4  gunspec.firearms.listMedia(id),5  gunspec.firearms.getOffers(id, { region: shopper.country }),6])7 8const rows = offers.data.map((offer) => ({9  vendor: offer.vendor.name,10  // Integer minor units. Format, never divide into a float.11  price: new Intl.NumberFormat(locale, { style: 'currency', currency: offer.currency })12    .format(offer.priceCents / 100),13  inStock: offer.inStock,14  // The counted redirect, not offer.url. This is what tells a15  // seller their placement worked.16  href: `${API}/v1/out/${offer.clickId}`,17  rel: 'nofollow sponsored',18}))

Prices are integers

Money on this API is integer minor units plus an ISO 4217 code. A float is refused at the boundary, and the reason is the one every commerce team has already met.

• priceCents is minor units: 58900 with currency: "USD" is $589.00. Divide only at render, inside Intl.NumberFormat.
• Never round on the way in. A price stored as 589.0 is a price that becomes 588.99 somewhere downstream.
• Show the currency the offer names rather than converting. A converted price is a quote you cannot honour.
• inStock is what a seller reports. Treat it as a hint in the UI and let the shop be the authority at checkout.

Outbound links are counted

Send shoppers to /v1/out/{clickId} rather than to offer.url. The redirect records the visit for that listing and then sends the shopper to the shop, which is the one number that justifies a seller’s placement. The destination comes from the offer row and never from the request, so the link cannot be pointed anywhere else. Mark the anchor rel="nofollow sponsored", because a paid placement is what it is. The seller reference documents the route.

Pushing a seller feed

A shop writes with an ordinary key that has been named in Profile > Seller. There is no vendor scope on a key, which is why an integration reads /v1/vendor/shops first: it is handed a key and never a shop id.

1// There is no scope on the key itself, and an integration is handed2// a key rather than a shop id, so read the shops first.3const { data: shops } = await gunspec.vendor.shops()4const vendor = shops[0].id5 6const { data } = await gunspec.vendor.pushOffers(7  {8    offers: feed.map((row) => ({9      sku: row.sku,10      attachment_id: row.gunspecId,11      price_cents: row.priceCents,12      currency: row.currency,13      url: row.productUrl,14      in_stock: row.qty > 0,15      region: row.shipsTo,16    })),17  },18  { vendor },19)

• Full push is PUT, up to 500 rows, keyed by your own SKU. Ids we do not hold come back as unmatched rather than failing the batch.
• Repricing is PATCH on the SKU, with only the fields that changed. Resending the whole row is how a price job silently rewrites a product URL.
• Send stock_qty or in_stock, never both: a row carrying a quantity derives its flag from it. The quantity stays private; the flag is what shoppers see.
• A feed row is hidden after thirty days without a refresh, so run the job daily even when nothing changed.
• One key per storefront where you run several. A key named by two shops must say which one it is acting for.

Accessories that actually fit

The reason to build a marketplace on this catalog rather than a spreadsheet is that fitment is computed from mount interfaces, so a cross-sell rail can be correct. What fits what covers the engine and its confidence floors, and the artwork guide covers the pictures beside each row.