Build on top of ScanSewa

Overview

The ScanSewa Developer API is a read-only REST API that lets partners and your own apps read a restaurant's live data — orders, menu, tables, inventory, customers and sales analytics — plus receive real-time webhooks and push orders in from external channels. Responses are JSON; every request is authenticated with a scoped API key.

https://api.scansewa.com/api/public/v1

Quickstart

Make your first authenticated call in under a minute.

1. 1 In your ERP dashboard, open Developer API and create a key. Copy it — it's shown once.
2. 2 Grant it only the scopes your integration needs, then send it as a Bearer token on every request.
3. 3 Call an endpoint — or try it live in the API Explorer.

curl "https://api.scansewa.com/api/public/v1/orders?status=Completed&limit=10" \
  -H "Authorization: Bearer ssk_live_…"

A successful response is { success: true, … } with HTTP 200. If you get 401, re-check the key; 403 means the key is missing that endpoint's scope.

Authentication

Pass your key as a Bearer token, or use the x-api-key header. Keys are read-only and scoped to a single restaurant's data — keep them server-side and never ship them in a browser or mobile app.

Authorization: Bearer ssk_live_…

x-api-key: ssk_live_…

Scopes

Each key is limited to the scopes you grant it. Calling an endpoint outside the key's scopes returns 403. Grant the minimum a given integration needs.

customers:read returns personal data — only grant it to integrations that genuinely need contact details, and handle the data per your privacy obligations.

Rate limits

Every key is limited to 120 requests per minute. Standard RateLimit-* headers are returned on each response; exceeding the cap returns 429.

RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 41            // seconds until the window resets

When you receive a 429, wait until the window resets (see RateLimit-Reset) before retrying, and back off exponentially on repeated limits. Batch work into paginated list calls rather than many single-item lookups, and prefer webhooks over tight polling.

Pagination & filtering

List endpoints are paginated. Pass ?limit= (1–100, default 50) and ?page= (default 1); each response includes total and hasMore so you know when to stop. Loop until hasMore is false rather than assuming a fixed page count.

// Walk every page of a list endpoint
async function fetchAll(path, key) {
  const out = [];
  let page = 1;
  while (true) {
    const res = await fetch(`${path}?limit=100&page=${page}`, {
      headers: { Authorization: `Bearer ${key}` },
    });
    const body = await res.json();
    out.push(...body.data);
    if (!body.hasMore) break;   // stop when the API says there's no more
    page += 1;
  }
  return out;
}

Errors

Errors use standard HTTP status codes with a JSON { success: false, message } body — read message for a human-readable reason.

{
  "success": false,
  "message": "Key lacks the required scope: analytics:read"
}

Treat 401/403 as configuration problems (fix the key or scope, don't retry blindly). Retry 429 after the reset window, and retry 5xx with exponential backoff.

Endpoints

All endpoints are GET and relative to the base URL above. Query parameters are listed with each endpoint below.

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total": 128,
  "hasMore": true,
  "data": [
    {
      "id": "665f…",
      "status": "Completed",
      "paymentStatus": "Paid",
      "items": [
        { "menuItemId": "M-101", "name": "Margherita", "quantity": 2, "unitPrice": 450, "itemTotal": 900 }
      ],
      "subtotal": 900,
      "grandTotal": 1017,
      "table": "T4",
      "source": "dine-in",
      "customerName": "Asha",
      "createdAt": "2026-06-11T08:20:00.000Z"
    }
  ]
}

{
  "success": true,
  "data": {
    "orders": 128,
    "revenue": 184560,
    "averageOrderValue": 1441.88,
    "byStatus": [ { "status": "Completed", "count": 110, "revenue": 170200 } ],
    "bySource": [ { "source": "dine-in", "count": 80, "revenue": 120300 } ],
    "topItems": [ { "menuItemId": "M-101", "name": "Margherita", "quantity": 212, "revenue": 95400 } ]
  }
}

Response objects

Every list and detail endpoint returns the objects below inside data. Fields marked optional may be null or absent. New fields may be added over time — see Versioning.

API Explorer

Try any endpoint against the live API with one of your keys, then copy the request as cURL, JavaScript or Python.

curl "https://api.scansewa.com/api/public/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhooks

Register an endpoint in your ERP dashboard to receive signed event POSTs instead of polling. Each delivery carries X-ScanSewa-Event, X-ScanSewa-Delivery and X-ScanSewa-Signature headers. Failed deliveries retry with backoff (30s → 2h, 6 attempts).

{
  "id": "evt_9f2c…",            // unique — use for idempotency
  "type": "order.created",
  "createdAt": "2026-06-11T08:20:00.000Z",
  "data": { "id": "665f…", "status": "Pending", "grandTotal": 1017, "items": [ … ] }
}

import crypto from "crypto";

// In your webhook route (any language / framework), read the RAW request body
// and the signature header, then verify before trusting the payload.
function verifyScanSewaWebhook(rawBody, signatureHeader) {
  const parts = Object.fromEntries(                           // "t=...,v1=..."
    (signatureHeader || "").split(",").map(p => p.split("="))
  );
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)          // whsec_...
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1 || "")
  );
}

// if verifyScanSewaWebhook(rawBody, header) is true:
//   const event = JSON.parse(rawBody);   // { id, type, createdAt, data }
//   handle event.type, and dedupe on event.id

Respond 2xx within 10s to acknowledge, and dedupe on event.id — the same event may arrive more than once. Do slow work (writes, emails) after you've acknowledged.

Inbound channels

Channels let an external system — a delivery aggregator or your own app — push orders into ScanSewa. They land in the kitchen display, billing and reports like any other order. Create a channel in your ERP dashboard to get a signing secret and a unique URL, then POST signed orders:

POST https://api.scansewa.com/api/inbound/<channelId>/orders

import crypto from "crypto";

const secret = process.env.SCANSEWA_CHANNEL_SECRET;          // chsec_...
const body = JSON.stringify(order);
const t = Math.floor(Date.now() / 1000);
const v1 = crypto.createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");

await fetch("https://api.scansewa.com/api/inbound/<channelId>/orders", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-ScanSewa-Signature": `t=${t},v1=${v1}` },
  body,
});

Items resolve to your menu by id, a mapping table or name. To get status changes back, register an order.updated webhook.

Recipes

Common integrations, each as a short starting point. Combine endpoints and webhooks to fit your workflow.

Best practices

Versioning & stability

The API is versioned in the path — the current stable version is v1. We treat these as non-breaking and may ship them without a new version: adding a new endpoint, adding a new field to a response, or adding a new optional query parameter or webhook event.

Build tolerantly — ignore fields you don't recognise rather than failing on them, and don't depend on the ordering of array results unless documented. Any breaking change would ship under a new version path (e.g. /v2), and we'd give advance notice and a migration window before retiring an older one.

OpenAPI & SDKs

The whole API is described by an OpenAPI 3.0 spec — import it into Postman, Insomnia or Swagger UI, or generate a typed client in your language of choice. No key is needed to fetch it.

Generate a client with your usual toolchain (for example, an OpenAPI generator) and you get typed models for every object in the Response objects reference above.

Changelog

Notable, backwards-compatible additions to the Developer API, newest first.

Support

Stuck on an integration, or need an endpoint we don't expose yet? We're happy to help.

Found a security issue? See our responsible-disclosure program. For data handling, read the Privacy Policy.