Market --- email checkout (integrators)

Last updated: Apr 27, 2026Section: General

Market --- email checkout (integrators)

Mailoo does not host your storefront. The Market integration gives you a catalog API, optional order APIs for a simple "cart snapshot → order by email" flow, and dashboard APIs for the project owner to list orders and change status.

Related: catalog read and attributes --- market-catalog-csv{.interpreted-text role="doc"} / market-catalog-external-api{.interpreted-text role="doc"}. API key scopes --- ../../../api/authentication{.interpreted-text role="doc"}.

Architecture

  • Cart / catalog cache: Keep cart state in the integrator site (e.g. localStorage or a client store). Refresh prices using ``GET /api/v1/market/.../effective-price`` (or the same resolution rules) before submit so totals match the server.
  • Secrets: All ``X-API-Key`` calls run from your server or BFF, never from public browser bundles (see ../../../api/authentication{.interpreted-text role="doc"}).
  • Submit order: Your BFF **``POST``**s to Mailoo with ``market.order.submit``; Mailoo stores a line snapshot and resolved prices, sends a confirmation email to the buyer if platform SMTP is configured (GLOBAL_SMTP_* / GLOBAL_MAIL_FROM on the API host), and returns a one-time ``accessToken`` for read-only polling.
  • After submit: The buyer (or your SPA) can call ``GET /api/v1/market/public/orders/{orderId}?token=`` without an API key until the token expires. If the token is lost, the buyer only has the email and order id you surface in the UI.
  • Back office: The project owner uses Bearer routes under ``/api/v1/projects/{uid}/integrations/{id}/market/orders/...`` to list orders, read detail, and update status; see ../../../api/endpoints{.interpreted-text role="doc"}.

Create order (BFF)

  • ``POST {baseUrl}/api/v1/market/{projectUid}/integrations/{integrationId}/orders``
  • Headers: ``X-API-Key`` with ``market.order.submit`` (or FULL)
  • Body (JSON):
  • ``customerEmail`` (required) --- buyer address (normalized to lowercase)
  • ``items`` (required, non-empty) --- each item:
  • ``productId`` --- must be ``PUBLISHED`` in this integration
  • ``priceKindId`` --- must exist for the integration
  • ``quantity`` --- positive decimal string (e.g. "2", "1.5")
  • ``variantId`` --- required if the product has variants, omitted (or null) if it has none
  • ``measurementUnitId`` --- optional; defaults to the product's default + effective-price resolution rules
  • ``note``, ``metadata`` --- optional (integrator-defined)

Response (201): ``data.id``, ``data.status`` (starts as NEW), ``data.accessToken`` (store only in the buyer session / return to the client for UX), ``data.accessExpiresAt``, ``data.totalAmount``, ``data.currency``, and ``data.emailToCustomer`` (whether platform SMTP could send: SENT / FAILED / NOT_CONFIGURED).

Public read (buyer)

  • ``GET {baseUrl}/api/v1/market/public/orders/{orderId}?token={accessToken}``
  • Or ``X-Market-Order-Token: {accessToken}``
  • No ``X-API-Key``. Invalid/missing token returns 404 (same as unknown order) to avoid leaking existence.

Token TTL defaults to 72 hours; the API may set ``MARKET_ORDER_ACCESS_TOKEN_TTL_HOURS`` (1--720) on the Mailoo host.

Owner dashboard (JWT)

Authenticated routes (summary):

  • ``GET .../market/orders`` --- list (optional ``limit`` query, max 100)
  • ``GET .../market/orders/{orderId}`` --- full snapshot + line ``attributesSnapshot``
  • ``PATCH .../market/orders/{orderId}`` --- ``{ "status": "...", "note"?: "..." }`` (status transitions: terminal states ``REJECTED``, ``FULFILLED``, ``CANCELLED`` cannot move to a different status)
  • ``GET .../market/orders/{orderId}/status-events`` --- audit trail

Statuses: ``NEW``, ``PROCESSING``, ``CONFIRMED``, ``REJECTED``, ``FULFILLED``, ``CANCELLED``.

Scoping API keys

  • ``market.external-read`` --- only catalog **``GET``**s; use on a BFF that fetches product pages.
  • ``market.order.submit`` --- only ``POST .../orders``; can be a different restricted key on the checkout BFF.
  • You may use one FULL key only in trusted backends; for least privilege, split read vs submit as above.

:::: note ::: title Note :::

The Mailoo ``apps/web`` app is the admin console; customer-facing checkout runs on your site and calls Mailoo's public API the same way any third-party would. ::::

📚