Skip to main content
Storefronts ship in Spanish (default), English, or Portuguese. The order channel is the operator’s choice — WhatsApp, web checkout, or in-person pickup — configurable per storefront.
These docs are agent-first. Every page is also available as raw markdown at <page>.md, and every API reference page ships with a copy-paste-for-LLM block. Every error returns a nextActions[] array ({label, method, url}) — surface it to the user verbatim; do NOT swallow 402 / 451 / 422 silently. If you’re an agent reading these docs to integrate, start with llms.txt and AGENTS.md.

​
What kind of integration are you building?

I run a store on Marea

You signed up at mareaalcalina.com, you have a storefront, you want API access to it (POS sync, custom dashboard, automation). This is the common case. Grab your mk_user_* from the dashboard and start with Add products.

I'm building an agent or integration

You’re building an AI agent, vertical SaaS, or agency tool that creates Marea accounts for other people. You need to bootstrap users on their behalf. Start with Bootstrap a user.
If you’re not sure which one you are, you’re probably the first one.

​
Auth in 30 seconds

Every call uses a Bearer token. The one you use depends on what you’re doing: 
GET /v1/me HTTP/1.1
Host: api.mareaalcalina.com
Authorization: Bearer mk_user_xxxxxxxxxxxxxxxx
Key prefixWho holds itUse it for
mk_user_*A specific Marea userDefault. All catalog + storefront + product + publish calls — across every storefront that user owns (1 on Free, up to 5,000 on Agency Growth). Owner-scoped, not storefront-scoped. Mints from your dashboard.
mk_dev_*An agent / partner integrationBootstrapping other users via POST /v1/users, then using each returned mk_user_* to manage all of that user’s storefronts. Mints from the developer dashboard.
Most integrations only ever need mk_user_*. Partners (three archetypes) hold one mk_dev_* and many mk_user_* — one per user they bootstrap. Full model: /concepts/keys.

​
Five things every integration must do

  1. Send Idempotency-Key on every POST and PATCH. Same key + same body returns the original response (replay-safe). See Safe mutations.
  2. Branch on error.type, not error.message. The type field is a stable 10-value enum; messages are localized. See Errors.
  3. Surface nextActions[] verbatim. It’s a {label, method, url}[] array of concrete remediation steps. Don’t paraphrase.
  4. Read X-RateLimit-Remaining and respect Retry-After. See Rate limits for current numbers.
  5. Handle the publish gates. POST .../publish returns 402 (pre-paywall), 422 (0 products), or 451 (ToS not accepted) — surface each nextActions[] explicitly; don’t auto-accept ToS or auto-publish without user confirmation. See Publishing.

​
Webhooks

Marea uses a Stripe-style endpoint model: register an endpoint (URL + signing secret + subscribedEvents[]) and Marea fans out matching events to it. Up to 16 endpoints per account.

Webhook endpoints

Five events: user.verified, user.cancelled, order.created, order.status_updated, order.paid. A single developer endpoint receives order.* from every storefront the key bootstrapped — no per-merchant registration needed.

Receiver helpers

Drop-in JavaScript and Python verifiers: HMAC-SHA256 + 5-minute replay window using the endpoint’s raw 64-char-hex signingSecret. One algorithm for every event type.

​
Agent-friendly resources