Version 1

Seller website API

Push orders from your own store into SellerOS BD, read products and receive status updates. API access is available on every plan and uses tenant-scoped keys. Keys are shown once and stored only as hashes.

Bearer API keys

Create and revoke keys in Dashboard → Integrations.

HMAC signatures

Webhook payloads are signed with your tenant secret.

Idempotent writes

Repeat-safe order creation with Idempotency-Key.

Base URL and authentication

All endpoints are under /api/v1 on your SellerOS BD installation. Send your API key in the Authorization header. Keys begin with sk_live_.

GET /api/v1/products HTTP/1.1
Host: your-selleros-domain.example
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx

Endpoints

MethodPathPurpose
GET/api/v1/productsList products (paginated)
GET/api/v1/ordersList orders (paginated, filter by status)
POST/api/v1/ordersCreate an order (Idempotency-Key)
GET/api/v1/orders/:orderNumberRead an order with items and shipment
PATCH/api/v1/orders/:orderNumberUpdate order status
GET/api/v1/meVerify key, plan, limits and usage
GET/api/v1/export/ordersDownload orders as CSV
GET/api/v1/export/productsDownload products as CSV
POST/api/v1/webhooks/inboundReceive signed events from your store
GET/api/healthUptime probe (no key required)

Create an order

Requires Idempotency-Key. Repeating the same key returns the existing order instead of creating a duplicate. Prices are recalculated on the server from your product catalogue when productId is supplied; for custom line items provide name, quantity and unitPrice.

curl -X POST https://your-domain/api/v1/orders \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: store-order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "Rahim", "phone": "01712345678", "address": "House 4, Road 2", "district": "Dhaka" },
    "items": [ { "productId": "prod_xxx", "quantity": 2 } ],
    "shippingFee": 60,
    "paymentMethod": "COD",
    "notes": "Call before delivery"
  }'

Update an order status

Status changes follow the order lifecycle: PENDING → CONFIRMED → PROCESSING → READY_TO_SHIP → SHIPPED → DELIVERED. CANCELLED and RETURNED release reserved stock. An invalid move returns 422 INVALID_TRANSITION; nothing is changed.

curl -X PATCH https://your-domain/api/v1/orders/SO-00042 \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "SHIPPED", "note": "Handed to Steadfast" }'

Workspace, plan and usage

GET /api/v1/me confirms the key is live and returns the tenant, owner, effective plan, current period usage against limits, and webhook status. Use it as a connection test after creating a key.

{
  "data": {
    "tenant": { "id": "ten_xxx", "name": "Dhaka Fashion", "status": "ACTIVE" },
    "plan": { "key": "GROWTH", "limits": { "orders": 1000, "products": 500, "seats": 5 } },
    "usage": { "ordersThisPeriod": 184, "products": 96, "staff": 3 },
    "webhook": { "enabled": true, "url": "https://shop.example/api/selleros" }
  }
}

CSV export

Both export endpoints return UTF-8 CSV with a byte-order mark so Bangla renders correctly in Excel. Text that looks like a spreadsheet formula is neutralised on export. Optional filters: status for both, plusfrom and to ISO dates for orders.

curl -L "https://your-domain/api/v1/export/orders?status=DELIVERED&from=2026-11-01" \
  -H "Authorization: Bearer sk_live_xxx" -o orders.csv

Inbound events from your store

If your storefront needs to push payment or fulfilment updates back, send them to /api/v1/webhooks/inbound with the same API key and an HMAC signature made with the webhook secret shown in Dashboard → Integrations. Timestamps older than five minutes are rejected, and each event id is stored once so retries are safe.

const body = JSON.stringify({
  id: "pay_9f2c",                       // unique per event
  type: "order.payment.updated",
  data: { orderNumber: "SO-00042", paymentStatus: "PAID", paidAmount: 1260, paymentMethod: "BKASH" }
});
const ts = Math.floor(Date.now() / 1000).toString();
const sig = "sha256=" + crypto.createHmac("sha256", webhookSecret).update(ts + "." + body).digest("hex");

await fetch("https://your-domain/api/v1/webhooks/inbound", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_xxx",
    "Content-Type": "application/json",
    "X-SellerOS-Timestamp": ts,
    "X-SellerOS-Signature": sig
  },
  body
});

Supported type today is order.payment.updated with paymentStatus of UNPAID, PARTIAL, PAID or REFUNDED. Unknown types are stored and acknowledged without changing data.

Health check

GET /api/health returns 200 when the app can reach PostgreSQL and 503 otherwise. It exposes no tenant data and is suitable for uptime monitors and container health checks.

Webhook events

Configure your endpoint in Dashboard → Integrations. SellerOS BD sends order.created,order.status_changed and order.payment_changed events. Each request includes:

X-SellerOS-Signature: sha256=<hex hmac>
X-SellerOS-Timestamp: 1760000000
X-SellerOS-Event: order.created

Compute HMAC-SHA256(secret, timestamp + "." + rawBody) and compare in constant time. Reject requests older than 5 minutes. Return any 2xx response within 10 seconds; retries are at-least-once, so deduplicate by event ID.

const expected = crypto
  .createHmac("sha256", secret)
  .update(timestamp + "." + rawBody)
  .digest("hex");
if (header !== "sha256=" + expected) return res.status(401).end();

Errors

Errors use a stable shape. Validation errors return 422 with field details.

{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }

Rate limits

API keys are limited per key. If you receive 429, honour the Retry-After header. Contact us on WhatsApp if you need a higher limit for a legitimate integration.