canonical: https://jentic.com/apis/mareaalcalina.com/mareaalcalina

# Marea Alcalina API

The Marea Alcalina API builds and publishes online storefronts for small businesses, from the product list to delivery, pickup, dine-in, and WhatsApp settings. A storefront is created from a manifest with a name, language, currency, and businessType, products are added or edited under it, and a publish call takes it live. Developer keys can also bootstrap a Marea account for a user in one call, confirm it with a 6-digit email code, issue extra restricted user keys, and register signed webhook endpoints for user and order events.

## For AI agents

Create and publish Marea storefronts, add and edit products, bootstrap and verify merchant accounts, and register webhooks for user and order events.

## Scope

Does not process card payments, print shipping labels, or manage warehouse inventory across locations. Use for building, stocking, and publishing Marea storefronts and onboarding their merchants only.

## Capabilities

- Create a storefront from a manifest with name, language (es, en, or pt), currency, and businessType, including products and categories in the same call
- Add a product with title and price, plus optional salePrice, sku, stock, imageUrl, and tags, to an existing storefront
- Publish a storefront to take it live, with 402, 422, and 451 responses telling the agent why a publish was refused
- Bootstrap a merchant account, starter storefront, and restricted user key in one call, then verify it with the emailed 6-digit code
- Issue an additional restricted user key with chosen scopes for a verified user
- Register webhook endpoints for events such as user.verified, user.cancelled, and order.*, and rotate their signing secrets

## Use cases

### Agent-built storefront through Jentic

A merchant tells an agent what they sell, and the agent builds the shop. Through Jentic it creates a storefront with a name, language, currency, and businessType, adds products, and publishes. The Marea mk_ key is injected by Jentic at call time, so the agent never holds it.

Example prompt: POST `/v1/storefronts` with name 'Panadería Luna', language 'es', currency 'MXN', and businessType 'Panadería y Repostería', then POST `/v1/storefronts/{storefrontId}/products` with title 'Concha' and price 15, then POST `/v1/storefronts/{storefrontId}/publish`

### Merchant onboarding by a partner app

A developer integration signs merchants up without sending them through a web form. Creating a user with email, displayName, and sourceAgent returns the account, a restricted user key, and optionally a starter storefront, and emails a 6-digit code. When the merchant reads the code back, the verify call upgrades that same key to full scope.

Example prompt: POST `/v1/users` with email 'ana@example.com', displayName 'Ana', and sourceAgent 'my-agent', store the returned user key, then POST `/v1/users/{userId}/verify` with the 6-digit code the user reads back

### Product and price maintenance

Shops change prices and stock often. Products can be listed with cursor pagination, with includeHidden to see products marked hide, and patched one at a time, where nested objects deep-merge and arrays are fully replaced. This lets an agent apply a sale price or hide a sold-out item without rebuilding the shop.

Example prompt: GET `/v1/storefronts/{storefrontId}/products` with includeHidden true, then PATCH `/v1/storefronts/{storefrontId}/products/{productId}` setting salePrice 199 on the product titled 'Pastel de chocolate'

### Order and account event notifications

Integrations need to know when a merchant verifies or cancels, and when orders arrive. A webhook endpoint subscribes to events such as user.verified, user.cancelled, and order.*, and a developer endpoint covers every storefront that developer bootstrapped. The signing secret is shown once on creation and can be rotated, with no overlap window in v1.

Example prompt: POST `/v1/webhook_endpoints` with url 'https://example.com/hooks/marea' and subscribedEvents ['order.*', 'user.verified'], and store the returned signingSecret

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/storefronts` | Create a storefront from a manifest |
| POST | `/v1/storefronts/{storefrontId}/products` | Add a product |
| PATCH | `/v1/storefronts/{storefrontId}/products/{productId}` | Update a product |
| POST | `/v1/storefronts/{storefrontId}/publish` | Publish a storefront |
| POST | `/v1/users` | Bootstrap a merchant account |
| POST | `/v1/users/{userId}/verify` | Verify a user with the emailed code |
| POST | `/v1/webhook_endpoints` | Register a webhook endpoint |

## Key resources

- **Storefronts** — Create, list, read, update, and publish storefronts with branding, schedule, delivery, pickup, dine-in, and WhatsApp settings
- **Products** — Add, list, and update products in a storefront's product list
- **Users** — Bootstrap merchant accounts, verify them by email code, resend codes, poll status, and issue restricted keys
- **Webhook endpoints** — Register, list, read, update, delete, and rotate secrets for event webhooks

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 67 / 100
  - AI-Readiness & Agent Experience: 51 / 100
  - Agent Usability: 94 / 100
  - Security: 55 / 100
  - AI Discoverability: 79 / 100
- **View full report:** https://jentic.com/apis/mareaalcalina.com/mareaalcalina/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Marea by hand means handling its mk_ bearer keys, telling developer keys from user keys, and walking the email-code verification step before a user key gets full scope. Through Jentic you install once, import the Marea Alcalina API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Marea puts the storefront id in the URL path (`/v1/storefronts/{storefrontId}/...`), so a rule can pin your agent to one storefront and the operations you pick under it. You choose the operations it may call, so actions like publishing, webhook deletion, or user creation are not included unless you add them.
- **Credential handling:** Your Marea key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an online storefront' or 'add a product to my shop', and Jentic returns the matching Marea operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Shopify REST Admin API** — Full e-commerce platform admin for products, orders, and customers
- **Ecwid API** — Embeddable online store with catalog and order management
- **Stripe API** — Online payment processing

## FAQ

### Is there a Marea Alcalina MCP server?

You don't need an MCP server to give your agent the Marea Alcalina API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it. Storefront and product operations are found by intent when needed, so no extra tool definitions sit in the agent's context.

### What authentication does the Marea Alcalina API use?

Per its OpenAPI spec, operations use a bearer token in the Authorization header with a key of the form mk_dev_ (developer) or mk_user_ (user). The spec also declares an X-API-Key header carrying the same mk_ value for environments that cannot send Authorization. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.

### Why would a storefront publish fail?

The publish operation returns 402 if the plan does not permit publishing, 422 if the storefront has no products, and 451 if the terms of service have not been accepted. Republishing is idempotent, so an agent can retry once the cause is fixed.

### Can I limit what my agent is allowed to do with the Marea Alcalina API?

Yes. Write a rule that allows only product listing and product updates under `/v1/storefronts/{storefrontId}/products` for one storefront id, so a product-editing agent can change prices and stock in that shop but cannot publish, create users, or touch webhooks. Your own instance runs those calls.

### What are the rate limits for the Marea Alcalina API?

The spec states one specific limit: resending a verification code is limited per user to 3 per hour and 5 per day. GET `/v1/me` returns the rate-limit window for the calling key. For other limits, see the published spec at https://api.mareaalcalina.com/v1/openapi.json.

### How do I create and publish a storefront through Jentic?

Add the Marea Alcalina API to Jentic One from the directory and store your mk_ key once. Your agent searches for 'create an online storefront', calls POST `/v1/storefronts` with name, language, currency, and businessType, adds products, then calls the publish operation. To run it on your own infrastructure, install Jentic One from its GitHub repo.