# Marketplace

> Who the key belongs to and its rules: currencies, languages, what a listing needs, the shipping table, showrooms and warehouses.

Who the key belongs to and its rules: currencies, languages, what a listing needs, the shipping table, showrooms and warehouses. 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/locations`](#the-marketplaces-showrooms-and-warehouses) | The marketplace's showrooms and warehouses |
| GET | [`/v1/marketplace`](#get-the-callers-marketplace) | Get the caller's marketplace |

## The marketplace's showrooms and warehouses

`GET /v1/locations` · operation `listLocations`

Active ones, e.g. for a showroom page.

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

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

## Get the caller's marketplace

`GET /v1/marketplace` · operation `getMarketplace`

The marketplace the API key (or console session) belongs to. Handy for checking a key.

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

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

## Schemas

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

### ListOutputBody

| Field | Type | Notes |
|---|---|---|
| `items` * | [SiteBody](#sitebody)[] |  |

### PublicBody

| Field | Type | Notes |
|---|---|---|
| `currencies` * | string[] | ISO 4217 codes; the first is the default. Empty until chosen. |
| `id` * | string |  |
| `listings` * | [ListingRules](#listingrules) | What sellers need to know to list |
| `locales` * | string[] | BCP 47 language tags; the first is the default. |
| `name` * | string |  |
| `shipping` * | [ShippingBody](#shippingbody) | Delivery prices by size and zone (empty: listings have their own) |
| `slug` * | string |  |
| `term_kinds` * | [TermKindBody](#termkindbody)[] | Kinds of catalogue terms listings refer to, e.g. brand |

### SiteBody

| Field | Type | Notes |
|---|---|---|
| `active` * | boolean |  |
| `buyer_pickup` * | boolean | Buyers may collect purchases here |
| `city` * | string |  |
| `country` * | string |  |
| `created_at` * | string (date-time) |  |
| `id` * | string |  |
| `kind` * | string | one of `showroom`, `warehouse` |
| `line1` * | string |  |
| `name` * | string |  |
| `opening_hours` | string | Free text, e.g. Sundays 11–16 |
| `postal_code` * | string |  |

### ListingRules

| Field | Type | Notes |
|---|---|---|
| `attributes_schema` | any | JSON Schema for the marketplace's own listing fields |
| `min_images` * | integer | Photos needed to go on sale (to be valued, at least 1) |
| `require_approval` * | boolean | Listings are reviewed before they go on sale |
| `require_category` * | boolean |  |
| `required_terms` * | string[] | Term kinds a listing needs, e.g. brand |
| `valuations` * | boolean | Sellers may ask the marketplace to value a listing instead of setting a price |

### ShippingBody

| Field | Type | Notes |
|---|---|---|
| `booking` | [BookingBody](#bookingbody) | When buyers can choose their delivery time |
| `collection` | map of map of integer | Collecting from the seller, by size and the seller's zone; missing means quoted |
| `currency` | string | The rates' currency |
| `delivery` | map of map of map of integer | By option, size and the buyer's zone, in minor units; missing means quoted |
| `free_storage_weeks` | integer | Weeks of storage before the fee starts. ≥ 0; ≤ 104 |
| `options` | [ShippingOptionBody](#shippingoptionbody)[] | Delivery services, e.g. standard, white glove |
| `sizes` * | [ShippingSizeBody](#shippingsizebody)[] |  |
| `storage_fees` | map of integer | Per started month, by size, taken from the seller's payout |
| `zones` * | [ShippingZoneBody](#shippingzonebody)[] |  |

### TermKindBody

| Field | Type | Notes |
|---|---|---|
| `key` * | string |  |
| `names` * | map of string | Per language |

### BookingBody

| Field | Type | Notes |
|---|---|---|
| `horizon_days` * | integer | How far ahead buyers can book. ≥ 1; ≤ 120 |
| `lead_days` * | integer | The earliest slot is this many days after today. ≥ 0; ≤ 30 |
| `per_window` | integer | Deliveries per window; 0 is no limit. ≥ 0 |
| `time_zone` | string | e.g. Europe/Stockholm (the default) |
| `weekdays` * | integer[] | 1 is Monday, 7 Sunday |
| `windows` * | [BookingWindowBody](#bookingwindowbody)[] |  |
| `zones` * | string[] | Zone keys whose buyers book |

### ShippingOptionBody

| Field | Type | Notes |
|---|---|---|
| `about` | string |  |
| `key` * | string |  |
| `name` * | string |  |

### ShippingSizeBody

| Field | Type | Notes |
|---|---|---|
| `about` | string |  |
| `key` * | string |  |
| `name` * | string |  |

### ShippingZoneBody

| Field | Type | Notes |
|---|---|---|
| `countries` * | string[] | ISO codes, e.g. ["SE"] |
| `delivery_time` | string | Shown to buyers, e.g. 2–5 working days |
| `key` * | string |  |
| `name` * | string |  |
| `postal_prefixes` | string[] | None: the whole countries |

### BookingWindowBody

| Field | Type | Notes |
|---|---|---|
| `key` * | string |  |
| `label` * | string | e.g. 08–12 |