Developer API

Every Minori Midori store can expose a REST API and outbound webhooks, so the systems a distributor already runs (an ERP, a warehouse tool, an accounting stack, a pricing spreadsheet) can read and update the store without a person in the admin panel. The API is part of the Enterprise tier.

All requests go to your store’s own domain, and every response is scoped to that one store, the same database-enforced isolation described on our security page:

https://{your-store-domain}/api/v1

Examples on this page use the {your-store-domain} placeholder — the store admin’s Settings → APIpage shows your store’s exact base URL and request samples pre-filled with it.

Authentication

Staff create API keys in the store admin under Settings → API. Each key has a scope, read_only or read_write, and the full secret (mm_live_…) is shown exactly once at creation; only a hash is stored, so it can never be displayed again. Send it on every request:

curl https://{your-store-domain}/api/v1/products \
  -H "Authorization: Bearer mm_live_4f2a…"

• A missing, malformed, revoked, or wrong-store key always gets the same 401 unauthorized, with no detail about why.
• A read_only key calling any write endpoint gets 403 forbidden_scope.
• Revoking a key in settings takes effect within a minute and is permanent.

Conventions

• JSON in and out, UTF-8.
• Money is always integer cents (total_cents: 40650 is $406.50). Weights are integer hundredths of a pound.
• Timestamps are ISO 8601, UTC.
• Field names are snake_case. Unknown fields in responses must be ignored: we add fields without notice; we never remove or rename them within v1.
• Unknown fields in request bodies are rejected with 422.

Errors

Every non-2xx response uses one envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "The request body is invalid.",
    "fields": { "base_price_cents": "must be a positive integer" }
  }
}

Rate limits

Per store (shared by all its keys): 300 reads/minute and 60 writes/minute. Exceeding either returns 429 with a Retry-After header in seconds.

Idempotency

Every write endpoint accepts an optional Idempotency-Key header (up to 200 characters, unique per logical request). Retrying with the same key replays the original response instead of applying the change twice; reusing a key with a different payload returns 409 idempotency_conflict. Keys are kept for 24 hours.

curl -X POST https://{your-store-domain}/api/v1/products \
  -H "Authorization: Bearer mm_live_4f2a…" \
  -H "Idempotency-Key: erp-sync-2026-07-24-001" \
  -H "Content-Type: application/json" \
  -d '{"name": "Heirloom Tomatoes", "price_cents": 425, "unit": "lb"}'

Endpoints

curl "https://{your-store-domain}/api/v1/products?active=true&limit=50" \
  -H "Authorization: Bearer mm_live_4f2a…"

curl -X PATCH https://{your-store-domain}/api/v1/products/8d3f…-a1 \
  -H "Authorization: Bearer mm_live_4f2a…" \
  -H "Content-Type: application/json" \
  -d '{"base_price_cents": 725}'

curl -X PUT https://{your-store-domain}/api/v1/inventory/8d3f…-a1 \
  -H "Authorization: Bearer mm_live_4f2a…" \
  -H "Content-Type: application/json" \
  -d '{"adjust_by": -12}'

curl "https://{your-store-domain}/api/v1/orders?status=pending" \
  -H "Authorization: Bearer mm_live_4f2a…"

curl -X PUT https://{your-store-domain}/api/v1/orders/57/tracking \
  -H "Authorization: Bearer mm_live_4f2a…" \
  -H "Content-Type: application/json" \
  -d '{"carrier": "UPS", "tracking_number": "1Z999AA10123456784"}'

curl "https://{your-store-domain}/api/v1/reports/sales?group_by=product&period=month" \
  -H "Authorization: Bearer mm_live_4f2a…"

curl -X POST https://{your-store-domain}/api/v1/fresh-sheets/drafts \
  -H "Authorization: Bearer mm_live_4f2a…" \
  -H "Content-Type: application/json" \
  -d '{"title": "This week", "layout": "market", "color_override": "#246b45", "product_ids": ["8d3f…-a1", "72cc…-9e"]}'

Webhooks

Register up to five HTTPS endpoints in Settings → API, each subscribed to the events you choose. When something happens in the store, we POST a signed notification; no polling.

Event types

• order.created: an order was placed (any channel: storefront, AI assistant, or an automatic standing-order/subscription run)
• order.updated: staff amended an order’s items, prices, or promo code; the payload carries the new totals, the previous total, and a structured diff of the changes
• order.status_changed: an order moved through the pipeline
• order.cancelled: an order was cancelled
• order.paid: an order’s payment settled
• invoice.created: a net-terms invoice was issued
• invoice.paid: an invoice was paid
• stock.low: a tracked product crossed its low-stock threshold

Delivery format

POST https://your-endpoint.example.com/hooks/minori
Content-Type: application/json
X-Webhook-Event-Id: evt_5f0c1c1e-8b0a-4b62-9a51-2f4f1b7f2a10
X-Webhook-Event-Type: order.created
X-MinoriMidori-Signature: t=1753380191,v1=6f2a8c…

{
  "id": "evt_5f0c1c1e-8b0a-4b62-9a51-2f4f1b7f2a10",
  "type": "order.created",
  "created_at": "2026-07-24T18:03:11Z",
  "data": {
    "order_id": "b7e1…",
    "number": 57,
    "status": "pending",
    "fulfillment": "delivery",
    "payment_status": "net_terms_open",
    "total_cents": 40650,
    "customer_id": "19af…",
    "placed_at": "2026-07-24T18:03:11Z",
    "location_id": null
  }
}

Payloads are summaries frozen at event time; fetch current detail from the API. Any 2xx within 10 seconds counts as delivered. Redirects are not followed.

Verifying signatures

Each endpoint has a signing secret (shown in settings). The signature header carries a unix timestamp t and one or more v1 HMAC-SHA256 digests of ${t}.${raw request body}:

const crypto = require("node:crypto");

function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=", 2)),
  );
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 5 min

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  return header
    .split(",")
    .filter((p) => p.startsWith("v1="))
    .map((p) => p.slice(3))
    .some((sig) => {
      const a = Buffer.from(sig, "hex");
      const b = Buffer.from(expected, "hex");
      return a.length === b.length && crypto.timingSafeEqual(a, b);
    });
}

During the 24 hours after you rotate a secret, deliveries carry two v1 entries, one per secret, so rotation never drops a delivery.

Delivery semantics

• At-least-once: the same event can arrive more than once; deduplicate by id. Ordering across events is not guaranteed.
• Retries: failed deliveries retry after roughly 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, and 24 hours, then stop.
• Auto-disable: after 15 consecutive failures the endpoint is disabled and the store owner is emailed. Re-enable it in settings; events from the downtime are not re-sent, so reconcile with API reads.
• A slow or failing endpoint never slows the store itself; delivery is fully asynchronous.

What the API deliberately does not do

There is no order placement, no customer-account management, and no payment operation in v1; those flows stay in the storefront and admin, where their existing safeguards live. There is no sandbox mode yet; test with a read_onlykey, or against endpoints registered as paused. If your integration needs something that isn’t here, tell us; the surface grows by real demand.