Selling

Any signed-in user can sell. A listing starts as a draft, gets photos, and is published: straight on sale, to the marketplace’s team for approval, or to be valued first. All calls send the user’s session.

What the marketplace asks for

Read GET /v1/marketplace → listings before building the form:

Field	Meaning
min_images	Photos needed to go on sale (at least 1 to be valued).
require_category	A category is needed.
required_terms	Term kinds needed, e.g. ["brand"].
attributes_schema	A JSON Schema for the marketplace’s own fields (condition, dimensions…). Render a field per property and send the values in attributes.
valuations	Sellers may ask the team to value the listing instead of setting a price.
require_approval	The team reviews listings before they go on sale.

Statuses

draft ──publish──▶ published                       (no approval needed)
draft ──publish──▶ pending_approval ──▶ published   (the team approves)
                                     └─▶ denied     (with review_note)
draft ──publish {ask_valuation}──▶ pending_valuation ──▶ valuation_offered
valuation_offered ──accept──▶ pending_approval
valuation_offered ──counter──▶ pending_approval     (the team approves, denies or offers again)
published ──close──▶ closed ──publish──▶ …

GET /v1/me/listings returns the seller’s listings in every status, latest change first, with cursor paging.

1. Start a draft

POST /v1/me/listings
{ "title": "Lounge chair", "locale": "sv" }

A draft can be incomplete. Save as the seller goes: PUT /v1/me/listings/{id} replaces the listing’s content, so always send the whole form, not just the changed field.

Field	Notes
title, description	Plain text. locale is the language the seller writes in.
price	{ "amount": 650000, "currency": "SEK" }, minor units, one of the marketplace’s currencies. Leave it out when asking for a valuation.
category_id, terms	terms maps a kind to a term id: { "brand": "…", "designer": "…" }.
attributes	The marketplace’s own fields, matching attributes_schema.
location	{ "country": "SE", "postal_code": "…", "city": "…" }. A country is needed to publish.
delivery	How it can reach the buyer: shipping (with a price, or none for “ask for a quote”), pickup, buyer_arranged. At least one. See Shipping and delivery.
stock	1 unless the seller has several of the same.

2. Add photos

Send each photo as the request body, with its content type:

POST /v1/me/listings/{id}/images
Content-Type: image/jpeg

<the file's bytes>

• JPEG, PNG or WebP, up to 20 MB and 50 megapixels, at most 20 per listing.
• The answer is 202 with the image in processing. Its sizes are ready within seconds; poll GET /v1/me/listings/{id} until status is ready.
• PUT /v1/me/listings/{id}/images/order with every image id sets the order; the first is the main photo.
• DELETE /v1/me/listings/{id}/images/{image_id} removes one.

Upload from your server: the browser sends the file to your server, which streams it on with the user’s session.

3. Publish

POST /v1/me/listings/{id}/publish
{ "ask_valuation": false, "wants_storage": false }

• With approval on, only the basics are checked (title, photos, country, price), because the team completes the listing.
• ask_valuation: true (where valuations is on): no price needed; the listing goes to pending_valuation.
• wants_storage: true: the seller asks the marketplace to collect the listing and store it until it sells. The team books the collection; until then it stays with the seller.
• If anything is missing, the 422 lists every problem in errors, so you can mark all the fields at once.

A closed listing can be published again the same way.

Valuations

When the team has valued it, the listing is valuation_offered with:

• offer: the price offered, and offer_note, why.
• offer_schedule: price drops offered with it, if any.

The seller answers:

• POST /v1/me/listings/{id}/offer/accept: the offer becomes the price.
• POST /v1/me/listings/{id}/offer/counter with { "amount": 720000 }: their own price, in the offer’s currency.

Either way the listing goes to pending_approval. A denied listing has review_note with the reason; show it, and don’t offer to send it again.

On sale

• price_schedule lists the drops ahead: each step has months, amount, on (when it applies) and done. Show the seller what’s coming.
• custody says where it is (seller, collecting, stored), and site which showroom or warehouse. fulfilment says who delivers it (seller or marketplace).
• Editing a listing on sale keeps it on sale, so it must stay complete. Sellers can’t edit a listing while the team reviews it, and closed or denied listings can’t be edited.
• POST /v1/me/listings/{id}/close takes it off sale. DELETE removes a draft; a listing that was ever on sale is closed instead.

When it sells

The seller sees the order under GET /v1/me/orders?as=seller. If the seller delivers it themselves, they mark it sent with tracking details. See Checkout and orders. They’re paid once the buyer has it, after setting up payouts.

Emails mongrl sends sellers

When the team offers a price, denies a listing or puts it on sale, the seller gets an email linking to https://<your shop>/<lang>/account/listings/<id>. Build that page. See Pages your shop needs.