Merlion Fulfillment open platform

Endpoints & authentication

Production base https://api.merlion-fulfillment.com/v1. All calls must send Authorization: Bearer <API_KEY>, Content-Type: application/json; charset=utf-8, and we strongly recommend X-Request-Id (UUID v4) for end-to-end tracing. Multi-entity accounts can send X-MF-Account-Id for sub-merchant or store scope.

Common paths (excerpt; HTTP verbs in the handbook): GET /v1/orders, POST /v1/orders, GET /v1/orders/{id}, POST /v1/orders/{id}/cancel, GET /v1/inventory/skus, GET /v1/tracking, POST /v1/labels. List endpoints support cursor pagination and updated_since for incremental sync.

Keys are environment-scoped: production sk_live_…, sandbox sk_test_…. Rotate leaked keys in the console; old keys may overlap for up to 15 minutes.

Data model & versioning

Core types include Order, LineItem, Shipment, InventoryItem, WebhookDelivery. Order and fulfillment IDs are decoupled internally; externally use merchant_order_id and mf_fulfillment_id to cross-reference. Responses include api_version and schema_revision for client compatibility.

If semantics change, we first annotate via the X-MF-Deprecation “beta” header with sunset times; during the window old and new fields are returned in parallel, with the new field authoritative.

Rate limits & idempotency

Default 1,200 requests/min per app (2xx/4xx count; 429 and network failures excluded), with burst 100. Over limit returns 429 and Retry-After (seconds). Temporary raises for peak season require QPS and load-test reference IDs.

For all writes, send Idempotency-Key: <UUID>. The same key commits once within 24 hours; repeats return the first status and body. HTTP 409 is for “invalid state for this action” (not idempotency collision).

Errors & business codes

Error body: {"error":{"code":"...","message":"...","request_id":"..."}}. request_id lines up with X-Request-Id for tickets and log correlation.

Examples: MF-1001 order missing, MF-2003 SKU frozen, MF-3007 cut-off closed, MF-4002 label channel circuit-broken. Full list: PDF appendix A.

Webhook signing & delivery

Register callback URLs in the console over TLS. Body is JSON; header X-MF-Signature: v1=<hex> with HMAC-SHA256 over timestamp + "." + raw_body, using the console signing secret. Verify before returning 200. If you don’t respond 2xx within 5s, we retry 1s → 4s → 16s → 64s, up to 8 attempts, then to a dead-letter queue for manual pull.

Common event types: order.accepted, order.shipped, order.exception, inventory.threshold, label.generated. Deduplicate on event_id before updating your state machine.

Sandbox & go-live

Sandbox base https://sandbox.api.merlion-fulfillment.com/v1 uses synthetic stock and mock tracking—no real carrier calls. Webhooks go to your registered dev URL, isolated from production.

Before go-live: split keys by env, egress IP allowlists, verify webhooks, run at least one full order path, align SFTP / push reconciliation fields. Read-only pre-prod (limited) may be requested via ticket.

Request examples

Sample “query tracking” snippets. Paths, keys, and response shapes are authoritative in the PDF handbook.

Python

import requests

BASE = "https://api.merlion-fulfillment.com/v1"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "X-Request-Id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
}

def get_tracking(tracking_number: str) -> dict:
    r = requests.get(
        f"{BASE}/tracking",
        params={"tn": tracking_number},
        headers=HEADERS,
        timeout=8,
    )
    r.raise_for_status()
    return r.json()

if __name__ == "__main__":
    print(get_tracking("MF-SE-2026-00019827"))

Node.js (fetch)

import fetch from "node-fetch";

const BASE = "https://api.merlion-fulfillment.com/v1";
const headers = {
  Authorization: "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
  "X-Request-Id": crypto.randomUUID(),
};

export async function getTracking(trackingNumber) {
  const u = new URL(`${BASE}/tracking`);
  u.searchParams.set("tn", trackingNumber);
  const res = await fetch(u, { method: "GET", headers });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

getTracking("MF-SE-2026-00019827").then(console.log).catch(console.error);

cURL

curl -sS "https://api.merlion-fulfillment.com/v1/tracking?tn=MF-SE-2026-00019827" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 550e8400-e29b-41d4-a716-446655440000"

For sandbox, swap the base URL to https://sandbox.api.merlion-fulfillment.com/v1 and use a sk_test_ key.

Open API handbook (PDF)

The offline PDF includes signing, full error lists, inventory events, field dictionary, and a go-live checklist. Static file below; if it diverges from the live summary, follow merchant-console notices.