Developer API Documentation | ISMAN Engineering Company

Overview

The ISMAN Developer API allows you to integrate with our store programmatically. Build custom storefronts, sync inventory, process orders, and receive real-time webhook notifications. All API responses are returned in JSON format.

Base URL

https://tkwlwtqbmbjrigraffpz.supabase.co/functions/v1

REST Architecture

Standard HTTP methods. JSON request and response bodies.

Webhook Events

Real-time notifications for orders, payments, and shipments.

API Key Auth

Pass your key in the Authorization header.

Rate Limits

100 requests per minute per API key.

Authentication

All API requests must include a valid API key in the Authorization header. You can generate keys from your admin dashboard under Integrations.

http

Authorization: Bearer YOUR_API_KEY

Never expose your API key in client-side code. Use it only in secure server environments.

Products

GET/api/products

List all published products with filtering, pagination, and sorting.

Response

json

{
  "data": [
    {
      "id": "prod_abc123",
      "name": "Stainless Steel Prep Table",
      "slug": "stainless-steel-prep-table",
      "price": 24500,
      "currency": "KES",
      "category": "commercial-kitchen",
      "in_stock": true,
      "image_url": "https://...",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 156
  }
}

GET/api/products/:id

Retrieve a single product by its unique ID or slug.

Response

json

{
  "id": "prod_abc123",
  "name": "Stainless Steel Prep Table",
  "description": "Heavy-duty prep table...",
  "price": 24500,
  "currency": "KES",
  "variants": [
    { "sku": "SSPT-120", "size": "120x60cm", "price": 24500 }
  ],
  "images": ["https://..."],
  "in_stock": true,
  "tags": ["kitchen", "stainless"]
}

Orders

POST/api/orders

Create a new order. The response includes the order ID and checkout URL if a payment gateway is configured.

Request Body

json

{
  "items": [
    { "product_id": "prod_abc123", "quantity": 2, "variant_sku": "SSPT-120" }
  ],
  "customer": {
    "name": "Jane Wanjiku",
    "email": "jane@example.com",
    "phone": "+254712345678",
    "address": "123 Moi Avenue, Nairobi"
  },
  "payment_method": "mpesa"
}

Response

json

{
  "success": true,
  "order_id": 100001,
  "order_ref": "ISMAN-2026-100001",
  "status": "pending_payment",
  "total": 56840,
  "currency": "KES",
  "checkout_url": "https://...",
  "expires_at": "2026-07-20T12:00:00Z"
}

GET/api/orders/:id

Retrieve order details including items, payment status, and fulfillment tracking.

Response

json

{
  "id": 100001,
  "order_ref": "ISMAN-2026-100001",
  "status": "paid",
  "total": 56840,
  "currency": "KES",
  "items": [...],
  "payment": { "provider": "mpesa", "status": "confirmed" },
  "fulfillment": {
    "service": "Sendy",
    "status": "in_transit",
    "tracking_number": "SNDY-987654",
    "estimated_delivery": "2026-07-22"
  }
}

GET/api/orders

List orders for the authenticated account with optional status filter.

Response

json

{
  "data": [...],
  "meta": { "page": 1, "per_page": 20, "total": 8 }
}

Webhooks

Subscribe to real-time events by registering a webhook URL in your admin dashboard. We will POST a JSON payload to your endpoint whenever an event occurs.

Supported Events

order.createdorder.paidorder.shippedorder.deliveredpayment.succeededpayment.failedproduct.stock_lowproduct.updated

POSThttps://your-app.com/webhooks/isman

Example webhook payload you will receive.

Request Body

json

{
  "event": "order.paid",
  "timestamp": "2026-07-20T09:15:00Z",
  "data": {
    "order_id": 100001,
    "order_ref": "ISMAN-2026-100001",
    "total": 56840,
    "currency": "KES",
    "customer": { "email": "jane@example.com", "name": "Jane Wanjiku" }
  },
  "signature": "sha256=abc123..."
}

Verify webhook signatures by computing an HMAC-SHA256 of the raw request body using your webhook secret. Compare it to the value in the signature header.

javascript

const crypto = require('crypto');

const secret = 'whsec_your_webhook_secret';
const signature = req.headers['x-webhook-signature'];
const body = JSON.stringify(req.body);

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');

if (signature !== expected) {
  return res.status(401).send('Invalid signature');
}

Errors & Codes

The API uses standard HTTP status codes and returns a JSON error object with details to help you debug.

Code	Meaning	Description
200	OK	Request succeeded.
201	Created	Resource created successfully.
400	Bad Request	Malformed request or missing required fields.
401	Unauthorized	Invalid or missing API key.
404	Not Found	The requested resource does not exist.
429	Too Many Requests	Rate limit exceeded. Retry after 60 seconds.
500	Server Error	Something went wrong on our end. Contact support.

Error Response Format

json

{
  "error": {
    "code": "invalid_product_id",
    "message": "The product ID 'prod_xyz' does not exist.",
    "type": "invalid_request_error",
    "request_id": "req_abc123"
  }
}