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
Section titled “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
Section titled “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
Section titled “What a storefront usually has”- Browse: the shop, search and filters, listing pages, brand and designer pages. See Browsing and search.
- Accounts: sign-up, sign-in by password or emailed link, email confirmation, password reset. See Accounts and sign-in.
- Checkout: delivery, vouchers, the Stripe payment form, then the order page. See Checkout and orders.
- Selling: the sell form, photos, valuations, the seller’s listings and sales. See Selling and Payouts.
- Messages: questions about a listing, order messages and support. See Messages.
- The pages emails link to. See Pages your shop needs.
How the API behaves
Section titled “How the API behaves”- REST over HTTPS with JSON, described by one OpenAPI 3.1 spec 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. Writes accept an Idempotency-Key.
- Everything is versioned under
/v1. Changes withinv1only add things: new endpoints, new optional fields.
Next: the Quickstart.