Publish a storefront

Publish is the one operation that takes a storefront from draft to public — the URL becomes shareable, indexable, and live for end customers. Required scope: storefront:publish. Always require explicit user confirmation before calling — publish is user-visible.

Pre-flight checklist

Before calling publish:

The storefront must have at least one product (else 422 no_products).
The user must be on any active plan — Free, Basic, Pro, Business, or Agency. Pre-paywall accounts (just-signed-up, no plan picked) get 402.
The user must have accepted the dashboard ToS modal (else 451). The agent cannot bypass this.

Short-circuit with GET /v1/me if you want to surface a CTA before the publish round-trip:

{
  "plan": { "tier": "free", "limits": { "publishable": true, "products": 30, "storefronts": 1 } },
  "tosAcceptedAt": "2026-04-15T10:23:00Z"
}

If plan.limits.publishable is false or tosAcceptedAt is null, surface the appropriate next-action to the user before attempting publish.

Request

POST /v1/storefronts/{storefrontId}/publish — body is optional.

curl -X POST https://api.mareaalcalina.com/v1/storefronts/$STOREFRONT_ID/publish \
  -H "Authorization: Bearer $MAREA_USER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

const res = await fetch(
  `https://api.mareaalcalina.com/v1/storefronts/${storefrontId}/publish`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${userKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({}),
  },
);
const { storefront } = await res.json();
// Surface storefront._links.publicUrl to the user.

import uuid, requests

res = requests.post(
    f"https://api.mareaalcalina.com/v1/storefronts/{storefront_id}/publish",
    headers={
        "Authorization": f"Bearer {user_key}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={},
)
storefront = res.json()["storefront"]

Send { "versionId": "ver_xxx" } to publish a specific version snapshot; omit for auto-version (the common case — Marea creates a fresh snapshot from the current draft).

200 OK — success

{
  "storefront": {
    "id": "stf_9a8b7c6d5e4f3a2b1c0d9e8f",
    "name": "Tacos La Marea",
    "language": "es",
    "currency": "MXN",
    "businessType": "restaurant",
    "published": true,
    "publishedDate": "2026-05-10T18:30:00.000Z",
    "_links": {
      "previewUrl": "https://marea.pro/preview/pv_8c4b2e3a4b9d",
      "publicUrl": "https://marea.pro/tacos-la-marea",
      "editUrl": "https://mareaalcalina.com/dashboard/menu/stf_9a8b7c6d5e4f3a2b1c0d9e8f"
    }
  }
}

Surface _links.publicUrl to the user — that’s the share-and-print-and-QR-code URL.

The four error gates

Every error follows the §9.6 envelope verbatim. Branch on error.type + error.code; surface nextActions[] to the user without paraphrasing.

402 — plan paywall (`plan_blocks_publish`)

The user is pre-paywall (no plan picked yet). Surface error.upgrade.upgradeUrl as a CTA; do not retry until the user upgrades.

{
  "error": {
    "type": "plan_limit",
    "code": "plan_blocks_publish",
    "message": "Your plan does not permit publishing. Upgrade to publish this storefront.",
    "doc": "https://docs.mareaalcalina.com/concepts/plan-limits#publish-paywall",
    "param": null,
    "requestId": "req_30a9358b-70bd-44f3-aa5d-8983b558ad84",
    "requestLogUrl": "https://mareaalcalina.com/developers/logs/req_30a9358b-70bd-44f3-aa5d-8983b558ad84",
    "recoverable": true,
    "retryAfterMs": null,
    "nextActions": [
      { "label": "Pick a plan to publish.", "method": null, "url": "https://mareaalcalina.com/upgrade?planSource=api" }
    ],
    "upgrade": {
      "currentPlan": "free",
      "requiredPlan": "basic",
      "upgradeUrl": "https://mareaalcalina.com/upgrade?planSource=api"
    }
  }
}

422 — empty storefront (`no_products`)

The storefront has 0 products. Use nextActions[0].url to add a product before retrying.

{
  "error": {
    "type": "invalid_request",
    "code": "no_products",
    "message": "Cannot publish an empty storefront. Add at least one product first.",
    "doc": "https://docs.mareaalcalina.com/concepts/publishing#no-products",
    "param": null,
    "requestId": "req_30a9358b-70bd-44f3-aa5d-8983b558ad84",
    "requestLogUrl": "https://mareaalcalina.com/developers/logs/req_30a9358b-70bd-44f3-aa5d-8983b558ad84",
    "recoverable": true,
    "retryAfterMs": null,
    "nextActions": [
      { "label": "Add at least one product before publishing.", "method": "POST", "url": "/v1/storefronts/stf_9a8b7c6d5e4f3a2b1c0d9e8f/products" }
    ],
    "upgrade": null
  }
}

451 — ToS not accepted (`tos_required`)

The user hasn’t accepted the dashboard ToS modal. The agent cannot bypass — the user must complete the modal in their browser. Retry with the same Idempotency-Key after the user accepts.

{
  "error": {
    "type": "tos_not_accepted",
    "code": "tos_required",
    "message": "The account holder must accept the Marea Terms of Service before this storefront can be published.",
    "doc": "https://docs.mareaalcalina.com/concepts/tos-jurisdiction",
    "param": null,
    "requestId": "req_30a9358b-70bd-44f3-aa5d-8983b558ad84",
    "requestLogUrl": "https://mareaalcalina.com/developers/logs/req_30a9358b-70bd-44f3-aa5d-8983b558ad84",
    "recoverable": true,
    "retryAfterMs": null,
    "nextActions": [
      { "label": "Open the dashboard so the user can accept the Terms of Service.", "method": "GET", "url": "https://mareaalcalina.com/dashboard/tos" }
    ],
    "upgrade": null
  }
}

404 — not found (`storefront_not_found`)

Wrong storefrontId, or this user-key doesn’t own it. Cross-tenant returns 404 (leak-less), not 403 — you cannot infer existence.

Summary table

HTTP	`error.type` / `code`	Why	What to do
402	`plan_limit` / `plan_blocks_publish`	Pre-paywall account	Surface `error.upgrade.upgradeUrl`; do not retry until upgrade.
422	`invalid_request` / `no_products`	0 products	Use `error.nextActions[0]` (POST products URL), then retry.
451	`tos_not_accepted` / `tos_required`	ToS modal not completed	Surface `nextActions[0].url` (dashboard). Agent cannot bypass. Retry with same `Idempotency-Key` after user accepts.
404	`not_found` / `storefront_not_found`	Wrong id or cross-tenant	Confirm id + ownership; cannot retry blindly.
429	`rate_limited` / `rpm_exceeded`	Per-user `rpm: 60` cap	Sleep `Retry-After`, retry with same key.

Idempotent republishing

Calling publish on an already-published storefront with the same versionId is a no-op that returns 200 with the same DTO. To republish a new version, omit versionId (auto-version) — Marea creates a fresh snapshot, runs the publish, and the live URL points at the new content. You can keep the same Idempotency-Key across retries of the same publish attempt; generate a fresh key for a new republish.

Cross-references

Publishing concept — full gate semantics + idempotency rules.
ToS jurisdiction — what the 451 ToS modal contains.
Plan limits — per-plan storefront caps + the publish-block-on-pre-paywall rule.

Get Started

Concepts

Webhooks

Publish a storefront

Publish a storefront

Pre-flight checklist

Request

200 OK — success

The four error gates

402 — plan paywall (`plan_blocks_publish`)

422 — empty storefront (`no_products`)

451 — ToS not accepted (`tos_required`)

404 — not found (`storefront_not_found`)

Summary table

Idempotent republishing

Cross-references

​Publish a storefront

​Pre-flight checklist

​Request

​200 OK — success

​The four error gates

​402 — plan paywall (plan_blocks_publish)

​422 — empty storefront (no_products)

​451 — ToS not accepted (tos_required)

​404 — not found (storefront_not_found)

​Summary table

​Idempotent republishing

​Cross-references

Publish a storefront

Pre-flight checklist

Request

200 OK — success

The four error gates

402 — plan paywall (`plan_blocks_publish`)

422 — empty storefront (`no_products`)

451 — ToS not accepted (`tos_required`)

404 — not found (`storefront_not_found`)

Summary table

Idempotent republishing

Cross-references