# Favourites

> Listings a user has saved.

Listings a user has saved. 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/favorites`](#list-saved-listings) | List saved listings |
| PUT | [`/v1/me/favorites/{id}`](#save-a-listing) | Save a listing |
| DELETE | [`/v1/me/favorites/{id}`](#remove-a-saved-listing) | Remove a saved listing |

## List saved listings

`GET /v1/me/favorites` · operation `listFavorites`

Latest saved first, including listings no longer on sale (check status).

**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 |
| `currency` | query | string | Show prices in this currency too (display_price); one of the marketplace's |

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

## Save a listing

`PUT /v1/me/favorites/{id}` · operation `saveFavorite`

Only listings on sale. Saving twice is fine.

**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)

## Remove a saved listing

`DELETE /v1/me/favorites/{id}` · operation `removeFavorite`

**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)

## Schemas

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

### SearchOutputBody

| Field | Type | Notes |
|---|---|---|
| `items` * | [ListingBody](#listingbody)[] |  |
| `next_cursor` | string |  |
| `total` * | integer | How many listings match |

### 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 |

### Delivery

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

### 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 |

### 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 |  |

### LocationBody

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

### 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 |