Merchant House Admin API

A REST API for connecting your store to the rest of your business: sync products and stock with a warehouse or ERP, pull orders into your fulfillment tools, and react to events with webhooks. Every request is scoped to one store.

https://api.merchanthouse.app

Prefer a machine-readable spec? The full OpenAPI 3.1 document works with Postman, Insomnia and code generators.

Authentication

Create a secret key in Dashboard → Settings → Developers. Pick only the scopes your integration needs. The full key (mh_sk_...) is shown once; store it in your server's secret manager, never in browser or mobile code. Send it as a bearer token:

curl https://api.merchanthouse.app/v1/store \
  -H "Authorization: Bearer mh_sk_..."

Revoking a key in the dashboard takes effect immediately. Requests with a missing or invalid key get 401; a valid key without the needed scope gets 403. Changes made through the API appear in the store's activity log.

Scopes

Requests & money

• HTTPS and JSON only. Send bodies with Content-Type: application/json; the limit is 1 MB.
• Money is always an integer in minor units, in requests and responses: 1999 is $19.99 in a USD store. The store currency is on GET /v1/store and on every product and order.
• Timestamps are ISO 8601 in UTC. Ids are prefixed strings (prd_, var_, ord_, oli_, cus_, loc_).
• Every response has an X-Request-Id header. Include it when you contact support.
• The API is server-to-server: there is no CORS support, so browsers cannot call it directly.

Pagination

List endpoints take page (1-based) and limit (1 to 100, default 50) and return a list envelope. Keep requesting page + 1 while has_more is true.

{
  "object": "list",
  "data": [ { "object": "product", "id": "prd_...", ... } ],
  "page": 1,
  "has_more": true
}

Errors

Errors use standard HTTP status codes and a consistent body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "variants.0.price: price must be an integer amount in minor units, e.g. 1999 for $19.99",
    "param": "variants.0.price",
    "request_id": "req_3f1c9a0e2b7d4c6a8e9f0a1b"
  }
}

Rate limits

Each key may make 120 requests per minute. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). Over the limit you get 429 with a Retry-After header; wait that many seconds and retry. For bulk jobs, spread requests out or use several narrowly scoped keys.

Idempotency

POST requests accept an Idempotency-Key header (any unique string up to 255 characters, such as a UUID). If a network error leaves you unsure whether a request succeeded, retry it with the same key and the same body: you get the original response back with Idempotent-Replayed: true instead of a duplicate product or fulfillment. Reusing a key with a different body returns 400 idempotency_error.

curl https://api.merchanthouse.app/v1/store \
  -H "Authorization: Bearer $MH_API_KEY"

curl https://api.merchanthouse.app/v1/products?status=active&limit=20 \
  -H "Authorization: Bearer $MH_API_KEY"

curl -X POST https://api.merchanthouse.app/v1/products \
  -H "Authorization: Bearer $MH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Hill Country Blend",
    "status": "active",
    "description": "<p>Medium roast with notes of pecan and dark chocolate.</p>",
    "tags": ["coffee", "whole bean"],
    "options": [{ "name": "Size", "values": ["12 oz", "2 lb"] }],
    "variants": [
      { "option1": "12 oz", "price": 1800, "sku": "HCB-12", "inventory_quantity": 40, "weight_grams": 340 },
      { "option1": "2 lb", "price": 4200, "sku": "HCB-32", "inventory_quantity": 12, "weight_grams": 907 }
    ]
  }'

curl https://api.merchanthouse.app/v1/products/prd_01jc6x2v9k8m3q7r5t4w2y0z1a \
  -H "Authorization: Bearer $MH_API_KEY"

curl -X PATCH https://api.merchanthouse.app/v1/products/prd_01jc6x2v9k8m3q7r5t4w2y0z1a \
  -H "Authorization: Bearer $MH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "archived", "tags": ["coffee", "seasonal"] }'

curl -X DELETE https://api.merchanthouse.app/v1/products/prd_01jc6x2v9k8m3q7r5t4w2y0z1a \
  -H "Authorization: Bearer $MH_API_KEY"

curl https://api.merchanthouse.app/v1/collections \
  -H "Authorization: Bearer $MH_API_KEY"

curl https://api.merchanthouse.app/v1/locations \
  -H "Authorization: Bearer $MH_API_KEY"

curl https://api.merchanthouse.app/v1/inventory_levels?sku=HCB-12 \
  -H "Authorization: Bearer $MH_API_KEY"

curl -X POST https://api.merchanthouse.app/v1/inventory_levels/set \
  -H "Authorization: Bearer $MH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variant_id": "var_01jc6x2v9k8m3q7r5t4w2y0z1b", "location_id": "loc_01jc6x2v9k8m3q7r5t4w2y0z1c", "available": 25 }'

curl https://api.merchanthouse.app/v1/orders?status=unfulfilled \
  -H "Authorization: Bearer $MH_API_KEY"

curl https://api.merchanthouse.app/v1/orders/ord_01jc6x2v9k8m3q7r5t4w2y0z1d \
  -H "Authorization: Bearer $MH_API_KEY"

curl -X POST https://api.merchanthouse.app/v1/orders/ord_01jc6x2v9k8m3q7r5t4w2y0z1d/fulfillments \
  -H "Authorization: Bearer $MH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "carrier": "UPS", "tracking_number": "1Z999AA10123456784", "notify_customer": true }'

curl https://api.merchanthouse.app/v1/customers?q=smith \
  -H "Authorization: Bearer $MH_API_KEY"

curl https://api.merchanthouse.app/v1/customers/cus_01jc6x2v9k8m3q7r5t4w2y0z1e \
  -H "Authorization: Bearer $MH_API_KEY"

Webhooks

Add an endpoint URL in Dashboard → Settings → Developers and choose events. Merchant House sends a POST with a JSON body { id, type, created_at, data }, where data is the same resource shape the API returns (orders and products).

order.createdorder.fulfilledorder.refundedorder.cancelledproduct.createdproduct.updatedproduct.deletedinventory.updated

• Respond with any 2xx within 10 seconds. Anything else is retried after 1 min, 5 min, 30 min, 2 h, 12 h and 24 h; an endpoint is disabled after 50 consecutive failures.
• Headers: Merchant-House-Event, Merchant-House-Delivery (stable across retries; use it to de-duplicate) and Merchant-House-Signature.
• Deliveries can arrive out of order. When order matters, re-fetch the resource from the API.

Verifying signatures

The signature header looks like t=1767225600,v1=5f2b.... v1 is the hex HMAC-SHA256 of {t}.{raw body} using your endpoint's signing secret (whsec_...). Compute it over the exact bytes you received, compare in constant time, and reject old timestamps.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.MH_WEBHOOK_SECRET; // whsec_...

// Use the raw body: re-serialized JSON will not match the signature.
app.post("/webhooks/merchant-house", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Merchant-House-Signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  const raw = req.body.toString("utf8");

  const expected = crypto.createHmac("sha256", SECRET).update(t + "." + raw).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "hex");
  const valid =
    given.length === 32 &&
    crypto.timingSafeEqual(given, Buffer.from(expected, "hex")) &&
    Math.abs(Date.now() / 1000 - t) < 300; // reject replays older than 5 minutes

  if (!valid) return res.status(400).send("bad signature");

  const event = JSON.parse(raw); // { id, type, created_at, data }
  // De-duplicate on the Merchant-House-Delivery header (stable across retries).
  console.log(event.type, event.data.id);
  res.sendStatus(200);
});