# 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_(dev|user)_... > 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 - [Bootstrap a user account](https://docs.mareaalcalina.com/quickstart/bootstrap.md): two-call flow — `POST /v1/users` creates account + storefront + restricted user-key; user verifies the 6-digit emailed code via `POST /v1/users/:userId/verify`. - [Add and edit products](https://docs.mareaalcalina.com/quickstart/products.md): user-key CRUD on the catalog. - [Publish a storefront](https://docs.mareaalcalina.com/quickstart/publish.md): the 402 (paywall) and 451 (ToS) flows, with `nextActions[].url` handling. - [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. - [Two-tier keys: developer (`mk_dev_*`) vs user (`mk_user_*`)](https://docs.mareaalcalina.com/concepts/keys.md) — eight scopes: `developer:bootstrap`, `developer:read`, `developer:issueUserKey`, `catalog:read`, `catalog:write`, `storefront:publish`, `me:verify`, `me:resendVerification`. Restricted user keys hold only `me:verify` + `me:resendVerification` until the 6-digit code is verified, then they're upgraded to full catalog scopes 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. - [Agent webhooks: user.* events on developer keys](https://docs.mareaalcalina.com/concepts/webhooks.md) — `user.verified`, `user.cancelled`. Configured per developer in `/developers/webhooks`. HKDF-derived signing key. - [Page webhooks: order.* events on a merchant store](https://docs.mareaalcalina.com/concepts/page-webhooks.md) — `order.created`, `order.status_updated`, `order.paid`. Configured per merchant in `/menus/profile?section=integrations`. Raw 32-byte hex signing secret (no HKDF). Disambiguate from Agent webhooks via `X-Marea-Source: merchant` header. - [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/webhooks/userEvents](https://docs.mareaalcalina.com/api/webhooks/register-webhook-url) — register a webhook URL to receive `user.verified` and `user.cancelled` events for users your dev key bootstraps. Scope `developer:bootstrap`. - [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 - [Agent-webhook receiver helpers (JS canonical + Python port)](https://docs.mareaalcalina.com/api/webhooks/receiver-helpers.md) — verifies HMAC-SHA256 with 5-min replay window. HKDF-derived secret (developer-key surface). - [Page-webhook receiver helpers (JS + Python)](https://docs.mareaalcalina.com/api/webhooks/page-webhook-helpers.md) — verifies HMAC-SHA256 with 5-min replay window. Raw 32-byte hex secret (merchant store surface). - [Discoverability metadata: `/.well-known/api-catalog`](https://mareaalcalina.com/.well-known/api-catalog) — RFC 9727 link to OpenAPI spec.