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_xxxxxxxxxxxxxxxxxEndpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/products | List products (paginated) |
| GET | /api/v1/orders | List orders (paginated, filter by status) |
| POST | /api/v1/orders | Create an order (Idempotency-Key) |
| GET | /api/v1/orders/:orderNumber | Read an order with items and shipment |
| PATCH | /api/v1/orders/:orderNumber | Update order status |
| GET | /api/v1/me | Verify key, plan, limits and usage |
| GET | /api/v1/export/orders | Download orders as CSV |
| GET | /api/v1/export/products | Download products as CSV |
| POST | /api/v1/webhooks/inbound | Receive signed events from your store |
| GET | /api/health | Uptime 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.csvInbound 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.createdCompute 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.