# What mongrl is

> The pieces of a mongrl marketplace and who does what, before you write any code.

mongrl is a headless marketplace API. You build the storefront people see, in any stack you like. mongrl runs everything behind it: accounts, listings, search, checkout with Stripe, orders, payouts, shipping and messages. The marketplace's team runs the day-to-day in the **console**, mongrl's back office.

## The pieces

| Thing | What it is |
|---|---|
| **Marketplace** | One shop, with its own currencies, languages, commission, shipping table and rules. Every key, user and listing belongs to exactly one marketplace. |
| **Listing** | The thing on sale: title, description, photos, price, catalogue terms (brand, designer…) and the marketplace's own fields. Always "listing", never "item" or "product". |
| **Seller** | A user who lists. Any user can sell; they set up payouts with Stripe before they're paid. |
| **Buyer** | A user who buys. Same accounts as sellers. |
| **Order** | One purchase of one listing. It moves through states (`pending_payment`, `purchased`, `delivered`, `received`…) by named transitions. |
| **Operator** | Someone on the marketplace's team, working in the console: they value and approve listings, ship orders, answer messages and set the rules. Roles are `admin` and `viewer`. |
| **Console** | The marketplace's back office at `console.mongrl.com`. It's built on the same API, with its own sign-in. You don't build it. |

## Who builds what

- **You** build the storefront: pages, design, domain, your server. Call the API from your server with your secret key.
- **mongrl** runs the API, the database, payments, emails, timers (expired payments, automatic receipt, payouts) and the console.
- **The marketplace's team** sets things up in the console: currencies, commission, what a listing needs, shipping and delivery, showrooms and warehouses, API keys.

## What a storefront usually has

1. **Browse:** the shop, search and filters, listing pages, brand and designer pages. See [Browsing and search](https://dev.mongrl.com/guides/browsing.md).
2. **Accounts:** sign-up, sign-in by password or emailed link, email confirmation, password reset. See [Accounts and sign-in](https://dev.mongrl.com/guides/accounts.md).
3. **Checkout:** delivery, vouchers, the Stripe payment form, then the order page. See [Checkout and orders](https://dev.mongrl.com/guides/checkout.md).
4. **Selling:** the sell form, photos, valuations, the seller's listings and sales. See [Selling](https://dev.mongrl.com/guides/selling.md) and [Payouts](https://dev.mongrl.com/guides/payouts.md).
5. **Messages:** questions about a listing, order messages and support. See [Messages](https://dev.mongrl.com/guides/messages.md).
6. **The pages emails link to.** See [Pages your shop needs](https://dev.mongrl.com/guides/storefront-pages.md).

## How the API behaves

- REST over HTTPS with JSON, described by one [OpenAPI 3.1 spec](https://dev.mongrl.com/openapi.json) that's generated from the API's code, so it's always current.
- Money is an integer in minor units with its currency. Errors are [RFC 9457 problems](https://dev.mongrl.com/reference/conventions.md#errors). Writes accept an [Idempotency-Key](https://dev.mongrl.com/reference/conventions.md#idempotency).
- Everything is versioned under `/v1`. Changes within `v1` only add things: new endpoints, new optional fields.

Next: the [Quickstart](https://dev.mongrl.com/start/quickstart.md).