Public REST API & Webhooks
Connect external ERPs, logistics couriers, warehouse barcode scanners, and custom headless apps to your Joomni store using scoped secret keys and real-time HMAC-signed event webhooks.
Overview
Joomni exposes a versioned, enterprise-grade REST API at /api/v1/ and an event-driven Webhook Delivery Engine. Designed around modern commerce patterns (similar to Shopify), it gives external systems full, programmatic control over your catalog, orders, and stock levels without compromising security.
Authentication & API Keys
Every API call requires a secret API key generated in your dashboard under Settings › API & Webhooks. Keys are prefixed with jk_live_ and granted only the specific permission scopes you select.
| Field | What it does |
|---|---|
| Header Option 1 (Standard) | Authorization: Bearer jk_live_your_key_here |
| Header Option 2 (Custom) | X-Joomni-Access-Token: jk_live_your_key_here |
| Base URL | https://api.joomni.com/api/v1/ |
Permission Scopes
| Scope | What it allows |
|---|---|
| orders:read | View orders, order items, customer addresses, and financial/fulfillment statuses. |
| orders:write | Create orders, fulfill items with tracking details, and cancel orders with restock. |
| products:read | Browse the catalog, search items, inspect variants, images, and prices. |
| products:write | Create, update, and remove catalog items and variants. |
| inventory:read | Read inventory levels and audit history. |
| inventory:write | Adjust or set stock levels with automatic logging and multi-variant synchronization. |
| customers:read / write | Read and manage customer records, tags, and contact profiles. |
| leads:read / write | Read and manage inbound contact inquiries, consultation requests, RFP data, and CRM tags. |
| bookings:read / write | Access appointment schedules, booking requests, calendar slots, and staff assignments. |
| store:read | Inspect store metadata, currency, timezone, and active vertical settings. |
Core Endpoints (/api/v1)
1. Products
Read and update catalog items:
GET /api/v1/products— List products with pagination (?page=1&limit=20&search=shirt).GET /api/v1/products/:id— Retrieve single product details with all variants.POST /api/v1/products— Create a new product.PUT /api/v1/products/:id— Update product details.DELETE /api/v1/products/:id— Safely delete a product (unlinks order snapshots).
2. Orders & Fulfillment
Automate orders and book courier shipments:
GET /api/v1/orders— List store orders (filter by?status=PENDING&fulfillmentStatus=UNFULFILLED).GET /api/v1/orders/:id— Full order breakdown including line item snapshots and shipping address.POST /api/v1/orders/:id/fulfill— Mark an order fulfilled and attach tracking company / tracking number.POST /api/v1/orders/:id/cancel— Cancel an order with optional automatic stock restoration.
3. Inquiries & Leads (B2B / CRM)
Sync inbound contact form submissions with external CRMs (HubSpot, Salesforce, Zoho):
GET /api/v1/leads— List incoming inquiries with pagination (?page=1&limit=20&status=NEW).GET /api/v1/leads/:id— Retrieve specific inquiry with AI intent and qualification score.POST /api/v1/leads— Create a new lead or import from an external marketing channel.PUT /api/v1/leads/:id— Update lead status (CONTACTED,QUALIFIED,CONVERTED).
4. Inventory Adjustment
Direct stock updates for barcode scanners and warehouse integrations:
Live API Sandbox Console
Test requests interactively against your store’s live endpoints or examine sample response payloads and headers:
Live REST API Sandbox Console
Test live requests, inspect JSON schemas, and verify response formats directly from your browser.
Leave blank to test using your current logged-in store session, or paste an API key created under Settings › API & Webhooks.
Real-Time Webhooks
Instead of polling the API every minute, configure Webhooks to receive real-time HTTP POST notifications the millisecond an event occurs in your store.
| Topic | Sent when |
|---|---|
| leads/create | A visitor submits a contact form, consultation inquiry, or quote request. |
| leads/updated | A lead status, tag, or AI qualification score changes. |
| bookings/create | A client books an appointment, consultation, or service. |
| bookings/cancelled | An appointment is cancelled or rescheduled. |
| orders/create | A customer or staff member places an order. |
| orders/updated | An order’s financial or delivery status changes. |
| orders/fulfilled | An order is fulfilled or dispatched with a courier. |
| orders/cancelled | An order is cancelled or refunded. |
| products/create / update / delete | Catalog items are created, modified, or removed. |
| inventory/level_update | Stock is decremented by sales or adjusted by staff. |
| customers/create | A new customer profile is registered. |
Webhook Headers
| Header | Value |
|---|---|
| X-Joomni-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>"> |
| X-Joomni-Timestamp | The same Unix timestamp (seconds) that was signed. |
| X-Joomni-Event-Id | Unique per delivery attempt, e.g. evt_3f9a… Use it to ignore repeats. |
| X-Joomni-Topic | The event topic, e.g. orders/create. |
| X-Joomni-Store-Id | The store the event belongs to. |
| X-Joomni-Webhook-Id | The subscription that matched. |
| X-Joomni-Hmac-Sha256 | Deprecated. Base64 HMAC of the body only — it cannot detect replays. Verify X-Joomni-Signature instead. |
Webhook addresses must use https:// and resolve to a public host. Private, loopback and link-local addresses are refused, and redirects are not followed. Your endpoint should reply with a 2xx status within 10 seconds.
Verifying Webhook Signatures
Compute an HMAC-SHA256 of `${t}.${rawBody}` with your webhook’s signing secret and compare it to the v1 value in X-Joomni-Signature. Then reject the request if t is more than 5 minutes old, so a captured request cannot be replayed later.
Sign the raw body, not parsed JSON
express.raw({ type: 'application/json' }) on your webhook route.Find the signing secret under Settings › API & Webhooks › Subscriptions (Reveal or Copy).