# Selling

> A seller's own listings: drafts, photos, publishing, valuations and storage.

A seller's own listings: drafts, photos, publishing, valuations and storage. Generated from the [OpenAPI spec](https://dev.mongrl.com/openapi.json). Each endpoint says which key it needs; see [Authentication](https://dev.mongrl.com/guides/authentication.md).

| Method | Path | What it does |
|---|---|---|
| GET | [`/v1/me/listings`](#list-the-signed-in-sellers-listings) | List the signed-in seller's listings |
| POST | [`/v1/me/listings`](#start-a-listing) | Start a listing |
| GET | [`/v1/me/listings/{id}`](#get-one-of-the-sellers-listings) | Get one of the seller's listings |
| PUT | [`/v1/me/listings/{id}`](#replace-a-listings-content) | Replace a listing's content |
| DELETE | [`/v1/me/listings/{id}`](#delete-a-draft) | Delete a draft |
| POST | [`/v1/me/listings/{id}/close`](#take-a-listing-off-sale) | Take a listing off sale |
| POST | [`/v1/me/listings/{id}/images`](#add-a-photo) | Add a photo |
| PUT | [`/v1/me/listings/{id}/images/order`](#set-the-order-of-the-photos) | Set the order of the photos |
| DELETE | [`/v1/me/listings/{id}/images/{image_id}`](#remove-a-photo) | Remove a photo |
| POST | [`/v1/me/listings/{id}/offer/accept`](#accept-the-marketplaces-price) | Accept the marketplace's price |
| POST | [`/v1/me/listings/{id}/offer/counter`](#answer-the-marketplaces-price-with-your-own) | Answer the marketplace's price with your own |
| POST | [`/v1/me/listings/{id}/publish`](#put-a-listing-on-sale) | Put a listing on sale |

## List the signed-in seller's listings

`GET /v1/me/listings` · operation `listMyListings`

Every status, latest change first.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `limit` | query | integer | ≥ 1; ≤ 100; default `24` |
| `cursor` | query | string | next_cursor from the previous page |

**Responses:** `200` [PageOutputBody](#pageoutputbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Start a listing

`POST /v1/me/listings` · operation `createMyListing`

Saved as a draft; it may be incomplete until it's published.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Body** (`application/json`): [ListingInputBody](#listinginputbody)

**Responses:** `201` [ListingBody](#listingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Get one of the seller's listings

`GET /v1/me/listings/{id}` · operation `getMyListing`

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Responses:** `200` [ListingBody](#listingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Replace a listing's content

`PUT /v1/me/listings/{id}` · operation `updateMyListing`

A listing on sale must stay complete. Closed listings can't be edited.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Body** (`application/json`): [ListingInputBody](#listinginputbody)

**Responses:** `200` [ListingBody](#listingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Delete a draft

`DELETE /v1/me/listings/{id}` · operation `deleteMyListing`

Listings that were ever on sale are closed instead.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Responses:** `204` No Content · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Take a listing off sale

`POST /v1/me/listings/{id}/close` · operation `closeMyListing`

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Responses:** `200` [ListingBody](#listingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Add a photo

`POST /v1/me/listings/{id}/images` · operation `uploadListingImage`

Send the photo as the body (JPEG, PNG or WebP, up to 20 MB and 50 megapixels). It's "processing" until its sizes are made, usually within seconds. At most 20 per listing.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Body** (`image/jpeg`): the file's bytes.

**Responses:** `202` [ImageBody](#imagebody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Set the order of the photos

`PUT /v1/me/listings/{id}/images/order` · operation `reorderListingImages`

Send every image id once; the first becomes the main photo.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Body** (`application/json`): [ReorderListingImagesRequest](#reorderlistingimagesrequest)

**Responses:** `200` [ListingBody](#listingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Remove a photo

`DELETE /v1/me/listings/{id}/images/{image_id}` · operation `deleteListingImage`

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |
| `image_id` * | path | string |  |

**Responses:** `204` No Content · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Accept the marketplace's price

`POST /v1/me/listings/{id}/offer/accept` · operation `acceptMyListingOffer`

The offer becomes the price and the listing waits for approval.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Responses:** `200` [ListingBody](#listingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Answer the marketplace's price with your own

`POST /v1/me/listings/{id}/offer/counter` · operation `counterMyListingOffer`

The seller's price is set and the listing waits for approval; the team approves it, denies it or makes a new offer.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Body** (`application/json`): [CounterMyListingOfferRequest](#countermylistingofferrequest)

**Responses:** `200` [ListingBody](#listingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Put a listing on sale

`POST /v1/me/listings/{id}/publish` · operation `publishMyListing`

From draft or closed. Goes to approval first if the marketplace requires it, with only the basics checked (title, photos, country, price), since the team completes the listing. With ask_valuation (where the marketplace offers valuations) no price is needed: the team offers one, which the seller accepts or answers with their own. If anything is missing, the 422 lists every problem.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Body** (`application/json`): [PublishMyListingRequest](#publishmylistingrequest)

**Responses:** `200` [ListingBody](#listingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Schemas

Fields marked * are always present in responses and required in requests.

### PageOutputBody

| Field | Type | Notes |
|---|---|---|
| `items` * | [ListingBody](#listingbody)[] |  |
| `next_cursor` | string |  |

### ListingInputBody

| Field | Type | Notes |
|---|---|---|
| `attributes` | map of any |  |
| `category_id` | string |  |
| `delivery` | [Delivery](#delivery) | At least one method is needed to publish |
| `description` | string | max 10000 chars |
| `locale` | string | The marketplace's default when omitted |
| `location` | [LocationBody](#locationbody) |  |
| `price` | [MoneyBody](#moneybody) |  |
| `shipping_size` | string | Operators: one of the marketplace's shipping sizes, which prices delivery; "" for none, omitted to leave it |
| `stock` | integer | 1 when omitted |
| `terms` | map of string | Catalogue term ids by kind, e.g. {"brand": "…"} |
| `title` | string | max 140 chars |

### ListingBody

| Field | Type | Notes |
|---|---|---|
| `attributes` * | map of any | The marketplace's own fields |
| `category_id` | string |  |
| `closed_at` | string (date-time) |  |
| `commission_percent` | number (double) | Console only: overrides the marketplace's commission; absent means the default |
| `created_at` * | string (date-time) |  |
| `custody` * | string | Where it is: at the seller's, being collected, or stored. one of `seller`, `collecting`, `stored` |
| `delivery` * | [Delivery](#delivery) | How the item can reach the buyer |
| `description` * | string |  |
| `display_price` | [MoneyBody](#moneybody) | The price in the requested currency, converted at the day's rate (approximate; the final amount is set at checkout) |
| `favorite_count` * | integer | How many users have saved it |
| `favorited` | boolean | Whether the signed-in user has saved it (only with X-User-Session) |
| `fulfilment` * | string | Who moves it to the buyer. one of `seller`, `marketplace` |
| `id` * | string |  |
| `images` * | [ImageBody](#imagebody)[] | In display order; the first is the main photo |
| `locale` * | string | The language the seller wrote in |
| `location` * | [LocationBody](#locationbody) |  |
| `offer` | [MoneyBody](#moneybody) | The price the marketplace offers (valuation_offered) |
| `offer_note` | string | A note with the offer |
| `offer_schedule` | [PriceStepBody](#pricestepbody)[] | The price drops offered with the price (valuation_offered) |
| `price` | [MoneyBody](#moneybody) | Base price, in the seller's currency |
| `price_schedule` | [PriceStepBody](#pricestepbody)[] | The price falls in these steps while on sale |
| `published_at` | string (date-time) |  |
| `review_note` | string | Why the marketplace denied it (denied) |
| `seller_blocked` | boolean | The seller is blocked, so the listing is out of the shop |
| `seller_id` * | string |  |
| `shipping_size` | string | Prices delivery from the marketplace's shipping table |
| `site` | [SiteRefBody](#siterefbody) | The marketplace location it's stored at or being collected to |
| `status` * | string | one of `draft`, `pending_valuation`, `valuation_offered`, `pending_approval`, `published`, `closed`, `denied` |
| `stock` * | integer |  |
| `stored_at` | string (date-time) | Stored since |
| `terms` * | map of [TermRefBody](#termrefbody) | By kind, e.g. brand |
| `title` * | string |  |
| `updated_at` * | string (date-time) |  |
| `wants_storage` | boolean | The seller asked to have it collected and stored |

### ImageBody

| Field | Type | Notes |
|---|---|---|
| `height` | integer |  |
| `id` * | string |  |
| `status` * | string | Sizes exist once ready. one of `processing`, `ready`, `failed` |
| `urls` | map of string | thumb (400 px square), medium (800 px), large (1600 px); cacheable forever |
| `width` | integer |  |

### ReorderListingImagesRequest

| Field | Type | Notes |
|---|---|---|
| `image_ids` * | string[] |  |

### CounterMyListingOfferRequest

| Field | Type | Notes |
|---|---|---|
| `amount` * | integer | In minor units, in the offer's currency. ≥ 1 |

### PublishMyListingRequest

| Field | Type | Notes |
|---|---|---|
| `ask_valuation` | boolean | Ask the marketplace to value it instead of setting a price |
| `wants_storage` | boolean | Ask the marketplace to collect and store it until it sells (otherwise it stays with the seller) |

### Delivery

| Field | Type | Notes |
|---|---|---|
| `buyer_arranged` | boolean |  |
| `pickup` | boolean |  |
| `shipping` | [Shipping](#shipping) |  |

### LocationBody

| Field | Type | Notes |
|---|---|---|
| `city` | string |  |
| `country` | string | ISO 3166-1 alpha-2, e.g. SE |
| `postal_code` | string |  |

### MoneyBody

| Field | Type | Notes |
|---|---|---|
| `amount` * | integer | In minor units: 125000 SEK is 1 250,00 kr. ≥ 0 |
| `currency` * | string | ISO 4217, one of the marketplace's |

### PriceStepBody

| Field | Type | Notes |
|---|---|---|
| `amount` * | integer | The new price, in minor units. ≥ 1 |
| `done` | boolean | It has applied |
| `months` * | integer | Months after the schedule starts (the listing goes on sale, or the schedule changes while on sale). ≥ 1; ≤ 60 |
| `on` | string (date-time) | When it applies (once on sale) |

### SiteRefBody

| Field | Type | Notes |
|---|---|---|
| `buyer_pickup` | boolean | Buyers may collect purchases here |
| `city` | string |  |
| `id` * | string |  |
| `kind` * | string | one of `showroom`, `warehouse` |
| `name` * | string |  |

### TermRefBody

| Field | Type | Notes |
|---|---|---|
| `descriptions` | map of string | About the brand, designer…, by locale (e.g. en, sv); on single listings only |
| `id` * | string |  |
| `name` * | string |  |
| `slug` * | string |  |

### Shipping

| Field | Type | Notes |
|---|---|---|
| `additional_item_price` | integer | ≥ 0 |
| `price` | integer | For the first item; omit for "ask for a quote". ≥ 0 |