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 (currently in early access; talk to us if you want it enabled for your store).

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

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://greenvalley.minorimidori.com/api/v1/products \
  -H "Authorization: Bearer mm_live_4f2a…"

• A missing, malformed, revoked, or wrong-store key always gets the same 401 unauthorized — 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://greenvalley.minorimidori.com/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://greenvalley.minorimidori.com/api/v1/products?active=true&limit=50" \
  -H "Authorization: Bearer mm_live_4f2a…"

curl -X PATCH https://greenvalley.minorimidori.com/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://greenvalley.minorimidori.com/api/v1/inventory/8d3f…-a1 \
  -H "Authorization: Bearer mm_live_4f2a…" \
  -H "Content-Type: application/json" \
  -d '{"adjust_by": -12}'

curl "https://greenvalley.minorimidori.com/api/v1/orders?status=pending" \
  -H "Authorization: Bearer mm_live_4f2a…"

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

curl "https://greenvalley.minorimidori.com/api/v1/reports/sales?group_by=product&period=month" \
  -H "Authorization: Bearer mm_live_4f2a…"

curl -X POST https://greenvalley.minorimidori.com/api/v1/fresh-sheets/drafts \
  -H "Authorization: Bearer mm_live_4f2a…" \
  -H "Content-Type: application/json" \
  -d '{"title": "This week", "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.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 — 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.