# Marea Alcalina API > Operations + retention layer for small-business commerce. This API lets agents > bootstrap a digital menu (food) or product catalog (retail and services) plus > a public hosted storefront for a single restaurant, store, or service business > — in under 10 calls. > > Storefronts ship in Spanish (default), English, or Portuguese. The order > channel is the operator's choice — WhatsApp, web checkout, or in-person pickup. > The API is channel-agnostic; agencies running multi-tenant ops mix-and-match > per storefront. Built for the single operator, not a generic enterprise > e-commerce backend. > > Default locale: es-MX. Currency: configurable per storefront. Phone format: E.164. > Auth: `Authorization: Bearer mk_user_...` (default) or `Bearer mk_dev_...` (partner integrations). > The user-key (`mk_user_*`) is the default credential for almost every integration. The developer-key (`mk_dev_*`) is a separate construct ONLY for agents/partners that need to bootstrap users on behalf of other people. Most integrations only ever hold `mk_user_*`. > **A user-key is owner-scoped, NOT storefront-scoped.** One `mk_user_*` covers ALL storefronts that user owns (1 on Free, up to 5,000 on Agency Growth). Do NOT issue a separate key per storefront. The storefront id is in the URL path; the key proves ownership. > Plans: Free (1 storefront, 30 products) → Basic (3 / 60) → Pro (15 / 200) → Business (50+ / 2000) → Agency. All can publish. Pre-paywall accounts (just signed up, no plan picked) cannot publish — `POST .../publish` returns 402 with `error.upgrade.upgradeUrl`. Always read live limits from `GET /v1/me` (`plan.limits`). > Always check `X-RateLimit-Remaining`; respect `Retry-After` on 429. > Every error returns `nextActions[]` (a `{label, method, url}` array) — surface to the user verbatim; do NOT swallow 402/451/422 silently. ## Quickstarts - [Add and edit products](https://docs.mareaalcalina.com/quickstart/products.md): **default flow.** User-key CRUD on the catalog. Start here if you own a Marea store. - [Publish a storefront](https://docs.mareaalcalina.com/quickstart/publish.md): the 402 (paywall) and 451 (ToS) flows, with `nextActions[].url` handling. - [Bootstrap a user account](https://docs.mareaalcalina.com/quickstart/bootstrap.md): **partner / agent flow.** Two-call: `POST /v1/users` creates account + storefront + restricted user-key; user verifies the 6-digit emailed code via `POST /v1/users/:userId/verify`. Use this if you're building an agent / vertical SaaS / agency that creates Marea accounts for *other* people. - [Install in Claude Desktop / Cursor / Continue.dev](https://docs.mareaalcalina.com/quickstart/mcp.md): paste-token MCP install; 7 `marea.*` tools (verify + resend stay REST-only by design). ## Concepts - [Storefronts: what they are](https://docs.mareaalcalina.com/concepts/storefronts.md) — public hosted pages that present a menu (food) or catalog (retail/services) and accept orders via WhatsApp, web checkout, or in-person pickup; channel is per-storefront config. - [Marea AI: the in-product chat editor](https://docs.mareaalcalina.com/concepts/marea-ai.md) — merchant-facing conversational editor in the dashboard; NOT a public API surface. Marea AI and the REST/MCP API write the same storefront model — two front doors to one catalog. There is no "send a prompt to Marea AI" endpoint; integrations use REST or MCP directly. - [API keys: user-key default, developer-key for partners](https://docs.mareaalcalina.com/concepts/keys.md) — `mk_user_*` is the default credential; holds `catalog:read`, `catalog:write`, `storefront:publish` (after verify) — used for ALL catalog and storefront operations. `mk_dev_*` is the partner credential; holds `developer:bootstrap`, `developer:read`, `developer:issueUserKey`, `developer:webhooks` — used ONLY to bootstrap users, never to touch a catalog. Restricted user-keys (returned by `POST /v1/users` pre-verify) hold only `me:verify` + `me:resendVerification` until verified, then upgraded in-place. - [Plan limits and the publish paywall](https://docs.mareaalcalina.com/concepts/plan-limits.md) - [Rate limits and 429 handling](https://docs.mareaalcalina.com/concepts/rate-limits.md) — `X-RateLimit-*` headers + `Retry-After`. - [Idempotency and safe mutations](https://docs.mareaalcalina.com/concepts/safe-mutations.md) — `Idempotency-Key`; reuse with different body returns 409. - [Verification flow (what users see)](https://docs.mareaalcalina.com/concepts/verification-flow.md) — user-reads-aloud + silent-via-Gmail-MCP variants. - [ToS + Mexican-law jurisdiction](https://docs.mareaalcalina.com/concepts/tos-jurisdiction.md) — 451 flow, modal copy. - [ARCO procedures (LFPDPPP)](https://docs.mareaalcalina.com/concepts/arco-procedures.md) — Mexican data-rights compliance. - [Webhook endpoints: Stripe-style endpoints with per-event subscription](https://docs.mareaalcalina.com/concepts/webhooks.md) — `user.verified`, `user.cancelled`, `order.created`, `order.status_updated`, `order.paid`. Each endpoint owns its URL, raw 64-char hex signing secret (32 random bytes), and `subscribedEvents[]` list. Developer endpoints can subscribe cross-scope to `order.*` events from merchants they bootstrapped. Up to 16 endpoints per owner. - [Publishing: ToS gate + plan paywall](https://docs.mareaalcalina.com/concepts/publishing.md) - [Errors: canonical taxonomy + agent recovery matrix](https://docs.mareaalcalina.com/concepts/errors.md) — branch on `error.type` (10-value enum), surface `nextActions[]` verbatim. - [Versioning policy](https://docs.mareaalcalina.com/concepts/versioning.md) ## API reference - [GET /v1/me](https://docs.mareaalcalina.com/api/identity/get-current-identity) — current key identity, scopes, plan tier, rate-limit budget. - [POST /v1/users](https://docs.mareaalcalina.com/api/users/bootstrap-user) — bootstrap a user + (optional) starter storefront + restricted `mk_user_*` key + email a 6-digit code. Scope `developer:bootstrap`. Returns 201, or **207 Multi-Status** if an `initialStorefront` manifest exceeded plan caps. - [GET /v1/users](https://docs.mareaalcalina.com/api/users/list-bootstrapped-users) — list every user this developer key bootstrapped. Paginated 50/page. Scope `developer:read`. - [GET /v1/users/:userId](https://docs.mareaalcalina.com/api/users/get-user) — poll the status of a bootstrapped user (verificationStatus, plan, recent events). Scope `developer:read`. Wrong `:userId` returns leak-less 404. - [POST /v1/users/:userId/verify](https://docs.mareaalcalina.com/api/users/verify-user-email) — submit the 6-digit code; upgrades the same `mk_user_*` in place to full per-user scope. Scope `me:verify`. Wrong `:userId` returns leak-less 404. - [POST /v1/users/:userId/resendVerification](https://docs.mareaalcalina.com/api/users/resend-verification-code) — re-issue a fresh 6-digit code; voids the previous one. Scope `me:resendVerification`. Per-user rate-limited: 3/hour, 5/day. - [POST /v1/users/:userId/keys](https://docs.mareaalcalina.com/api/users/issue-additional-user-key) — issue an additional restricted user-key for a verified user. Scope `developer:issueUserKey`. - [POST /v1/storefronts](https://docs.mareaalcalina.com/api/storefronts/create-storefront) — create a storefront from a manifest. Scope `catalog:write`. May return **207 Multi-Status** if the manifest exceeds plan caps (storefront created up to cap + `errors[]` describing skipped products). - [PATCH /v1/storefronts/:storefrontId](https://docs.mareaalcalina.com/api/storefronts/update-storefront) — partial PATCH. Deep-merge nested objects, full-replace arrays. Scope `catalog:write`. - [POST /v1/storefronts/:storefrontId/publish](https://docs.mareaalcalina.com/api/storefronts/publish-storefront) — take live. Returns **402** if pre-paywall, **422** if 0 products, **451** if user hasn't accepted ToS. Idempotent on republish. Scope `storefront:publish`. - [POST /v1/storefronts/:storefrontId/products](https://docs.mareaalcalina.com/api/products/add-product) — add a product. 201 on success, 402 `plan_max_products_reached` if at cap. Scope `catalog:write`. - [PATCH /v1/storefronts/:storefrontId/products/:productId](https://docs.mareaalcalina.com/api/products/update-product) — partial PATCH a product. Scope `catalog:write`. - [POST /v1/webhook_endpoints](https://docs.mareaalcalina.com/api/webhooks/create-webhook-endpoint) — create a webhook endpoint (URL + subscribedEvents). Returns the signingSecret ONCE. Scope `developer:webhooks` or `developer:bootstrap`. - [GET /v1/webhook_endpoints](https://docs.mareaalcalina.com/api/webhooks/list-webhook-endpoints) — list endpoints (no secrets). - [POST /v1/webhook_endpoints/:id](https://docs.mareaalcalina.com/api/webhooks/update-webhook-endpoint) — patch url / description / enabled / subscribedEvents. - [POST /v1/webhook_endpoints/:id/rotate-secret](https://docs.mareaalcalina.com/api/webhooks/rotate-webhook-endpoint-secret) — rotate signing secret; returns new value ONCE, old stops working immediately. - [DELETE /v1/webhook_endpoints/:id](https://docs.mareaalcalina.com/api/webhooks/delete-webhook-endpoint) — hard delete. - ~~POST /v1/webhooks/userEvents~~ — DEPRECATED 2026-05-12 (returns 200 but URL is ignored at dispatch; create an endpoint via /v1/webhook_endpoints instead). Removed next release. - [Live OpenAPI 3.1 spec](https://api.mareaalcalina.com/v1/openapi.json) — authoritative; 5-min cached. ## SDKs and tools - [OpenAPI 3.1 spec](https://api.mareaalcalina.com/v1/openapi.json) — authoritative; auto-generated from Zod contracts. - [Postman collection](https://docs.mareaalcalina.com/marea.postman.json) — auto-generated from OpenAPI at build time. - [MCP server](https://mcp.mareaalcalina.com) — 7 `marea.*` tools; paste-token install in Claude Desktop / Cursor / Continue.dev (verify + resend stay REST-only by design). - [`AGENTS.md` for consumers](https://docs.mareaalcalina.com/AGENTS.md) — common patterns + what NOT to do (call publish without user confirmation, swallow `nextActions[]`, cache user keys outside session). - [llms-full.txt](https://docs.mareaalcalina.com/llms-full.txt) — full-doc concatenation (Mintlify auto-emits). ## Optional - [Webhook receiver helpers (JS canonical + Python port)](https://docs.mareaalcalina.com/api/webhooks/receiver-helpers.md) — verifies HMAC-SHA256 with 5-min replay window using the endpoint's raw 64-char-hex `signingSecret`. One algorithm for all event types. - [Discoverability metadata: `/.well-known/api-catalog`](https://mareaalcalina.com/.well-known/api-catalog) — RFC 9727 link to OpenAPI spec.