Browsing and search

Everything a visitor sees before they sign in works with your secret key alone (a publishable key works too, from a native app).

Start from the marketplace

GET /v1/marketplace tells you how to build the shop:

Field	Use it for
currencies	The currency picker. The first is the default.
locales	Languages. The first is the default.
term_kinds	Which catalogue filters exist, e.g. brand, designer.
listings.attributes_schema	A JSON Schema of the marketplace’s own listing fields (condition, dimensions…). Filter on them with attr.
shipping	Delivery prices by size and zone, for “delivery from…” hints. See Shipping and delivery.

Cache it for a few minutes; it changes when the team edits Settings.

Search and filter

GET /v1/listings?q=lounge+chair&term=<brand id>&attr=condition:excellent&min_price=500000&currency=EUR&sort=newest&limit=24

Parameter	What it does
q	Words in the title, catalogue terms or description. Accents don’t matter and word beginnings match: “henn” finds Henningsen.
category	This category and everything under it.
term	Catalogue term ids; repeat it. Terms of one kind match any (brand A or B); different kinds must all match (brand A and designer C).
attr	key:value on the marketplace’s own fields; repeat it. Values of one key match any.
min_price, max_price	Minor units of currency, which is then required. Listings in other currencies are compared at the day’s rate.
seller	One seller’s listings, for a seller page.
currency	Adds display_price in this currency (one of the marketplace’s).
sort	relevance (the default with q), newest (the default without), price_asc, price_desc, popular (most saved).
limit, cursor	Paging. Pass next_cursor back as cursor; there’s no more when it’s absent.

The answer has items, total (how many match) and next_cursor. Only listings on sale are returned.

Prices

Every listing has price: what the seller set, in the listing’s currency. With currency, it also has display_price, converted at the day’s rate.

• Show display_price when you asked for one, otherwise price.
• Converted prices are approximate. The buyer pays what the quote says.
• Format with Intl.NumberFormat(locale, { style: 'currency', currency }) after dividing by 100 for currencies with two decimals.

const money = ({ amount, currency }: { amount: number; currency: string }, locale = 'sv-SE') =>
  new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount / 100)

A listing on sale may have a price_schedule: the price falls in steps while it doesn’t sell. The current price is already the dropped one, so you don’t need to work it out.

The listing page

GET /v1/listings/{id}?currency=EUR returns one listing on sale (404 otherwise). Useful fields:

• title, description, terms (by kind, each with name and slug), attributes, category_id.
• images in display order; the first is the main photo.
• delivery: how it can reach the buyer. See Shipping and delivery.
• site: the showroom or warehouse it’s stored at, when it is (buyer_pickup says whether buyers may collect it there).
• favorite_count, and favorited when you send the user’s session.
• seller_id, for a link to the seller’s other listings (?seller=).

Photos

Each image has status and urls:

Size	Use
thumb	400 px square, for grids
medium	800 px wide, for listing pages on phones
large	1600 px wide, for zoom

The URLs are public and can be cached forever; a changed photo gets a new URL. Only ready images have sizes.

Categories and catalogue terms

• GET /v1/categories?locale=sv returns the whole tree at once, with parent_id and position. Build the menu from it.
• GET /v1/catalog-terms?kind=brand&in_use=true returns every brand with listings on sale, each with listing_count, for a filter list.
• GET /v1/catalog-terms?kind=designer&q=hen filters by the start of the name, a page at a time, for a brand or designer index.
• GET /v1/catalog-terms/{kind}/{slug} returns one term, for a brand page at /brands/<slug>. Then list its listings with term=<id>.

Showrooms

GET /v1/locations returns the marketplace’s active showrooms and warehouses: address, opening hours and whether buyers may collect there. Use it for a “visit us” page.

Favourites

With the user’s session:

• PUT /v1/me/favorites/{listing id} saves, DELETE removes. Both are safe to repeat.
• GET /v1/me/favorites?currency=EUR lists them, newest first, with cursor paging.

Show the heart from favorited on listings you fetched with the session.