QuickShop

QuickShop API

Build your own website, app or back office on a QuickShop store. QuickShop keeps doing checkout, orders, WhatsApp messages and alerts; your code shows the catalog, places orders and hears about everything that happens.

Getting started

  1. The store owner opens Developers in the QuickShop dashboard and makes a key.
  2. Send it with every request: Authorization: Bearer qs_…
  3. Every address below starts with https://quickshop-mr5u.onrender.com/api/v1. Requests and responses are JSON; money is in Mauritian rupees (MUR); times are UTC (ISO 8601).
curl https://quickshop-mr5u.onrender.com/api/v1/products \
  -H "Authorization: Bearer qs_pk_your_publishable_key"

This is version 1. Fields may be added to responses, but nothing in v1 will be renamed or removed. Ignore fields you don't know.

Keys

Publishable qs_pk_…

Safe in browser or app code. Reads the catalog, quotes and places orders: exactly what the store's own storefront can do. Works from any website.

Secret qs_sk_…

Server only. Can do what its scopes allow. Never put it in a web page, an app or a public repository. If it leaks, revoke it in the dashboard: it stops working at once.

ScopeAllows
catalog:readProducts, categories, stock
catalog:writeAdd, change and delete products and categories
orders:readEvery order, with the customer's phone
orders:writePlace orders, change their status, mark them paid
customers:readNames, phones, order counts
site:deployPublish your own website (e.g. from GitHub Actions)
checkoutQuote and place orders, like your storefront

catalog:write includes reading the catalog; orders:write includes reading orders and checkout. Publishable keys have catalog:read and checkout.

Endpoints

RequestScopeWhat it does
GET/storeany keyThe store: name, address, currency, fulfilment and payment options
GET/categoriescatalog:readCategories
POST/categoriescatalog:writeAdd a category { name }
GET/products?category=&search=catalog:readEvery product, with price, stock, options and photos
GET/products/{id}catalog:readOne product
POST/productscatalog:writeAdd a product (categoryId and name required)
PATCH/products/{id}catalog:writeChange only the fields you send, e.g. { price } or { stock }
DELETE/products/{id}catalog:writeDelete a product
GET/delivery-zonescheckoutWhere the store delivers, with fees (pass a zone's id as deliveryZoneId)
POST/orders/quotecheckoutExact total (promo code and delivery fee included) before ordering
POST/orderscheckoutPlace an order, with the same rules as the storefront
GET/orders?status=&createdAfter=&limit=&cursor=orders:readOrders, newest first, 1–100 per page
GET/orders/{id}orders:readOne order
PATCH/orders/{id}/statusorders:write{ status }: Confirmed, Preparing, Ready, Completed or Cancelled
PATCH/orders/{id}/paymentorders:write{ paymentStatus }: Paid, or Pending (not received)
GET/customers?limit=&cursor=customers:readCustomers with order counts and totals
PUT/catalogcatalog:writeSync the whole catalog from your system, matched by externalId (see below)
POST/site/deployments?note=site:deployDeploy the store's own website: the body is its zip (application/zip)

Lists come back as { "data": [...], "nextCursor": "…" }. Pass nextCursor as ?cursor= to get the next page; it's null on the last one.

Placing an order

Orders follow the storefront's rules: stock, drops, product options, promo codes and delivery zones are all checked by QuickShop. Quote first to show the exact total.

const res = await fetch("https://quickshop-mr5u.onrender.com/api/v1/orders", {
  method: "POST",
  headers: {
    "Authorization": "Bearer qs_pk_your_publishable_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customerName: "Priya",
    customerPhone: "+230 5700 1234",
    fulfilmentType: "Pickup",          // Pickup, Delivery or DineIn
    location: "Port Louis",
    paymentMethod: "WhatsApp",         // WhatsApp, Card or QrCode
    items: [{ productId: "…", quantity: 2, options: { Size: "Large" } }],
    promoCode: null,
    deliveryZoneId: null,              // needed for Delivery when the store has zones
  }),
});
const order = await res.json();
// Send the customer to order.receiptUrl: live status, payment and review.

The response includes reviewToken. Keep it in the customer's browser: it proves they placed the order when they say they've paid or leave a review.

Your own website

Build the shop's website with anything (Lovable, Bolt, v0, React, plain HTML) and use the QuickShop kit for the catalog, the cart and checkout. Checkout ends on the store's QuickShop receipt page, where the customer follows the order, pays and leaves a review.

Hosted by QuickShop

The owner uploads a zip of the built site on Own website in the dashboard, or deploys it from CI with a secret key that has site:deploy. It's served at https://{store}--site.quickshop-mu.com, with the kit already loaded and connected: QuickShop.connect() needs no key there. Single-page apps work: unknown paths get index.html. The 5 newest deployments are kept for rollback. Limits: 25 MB unzipped, 2,000 files, 10 MB per file. Every page shows a small “QuickShop · Report” badge.

cd dist && zip -qr ../site.zip . && cd ..
curl -X POST "https://quickshop-mr5u.onrender.com/api/v1/site/deployments?note=v1.2" \
  -H "Authorization: Bearer qs_sk_key_with_site_deploy" \
  -H "Content-Type: application/zip" --data-binary @site.zip

Hosted anywhere else

<script src="https://quickshop-mr5u.onrender.com/sdk/v1/quickshop.js"></script>
<script>
  const shop = QuickShop.connect({ key: "qs_pk_your_publishable_key" });
</script>

The kit

const shop = QuickShop.connect();

await shop.store();                       // name, address, fulfilment and payment options
await shop.categories();
await shop.products({ category, search });
await shop.deliveryZones();

shop.cart.add(productId, 1, { Size: "Large" });   // kept in the browser
shop.cart.items(); shop.cart.count();
shop.cart.setQuantity(index, 3); shop.cart.remove(index);
shop.cart.onChange((lines) => render(lines));

await shop.quote({ fulfilment: "Delivery", deliveryZoneId, promoCode });
await shop.checkout({
  customerName: "Priya", customerPhone: "+230 5700 1234",
  fulfilment: "Pickup", location: "Port Louis",
});                                       // then opens the receipt page
shop.formatPrice(1250);                   // "Rs 1,250"

Errors are thrown as QuickShopError with the API's code and message. TypeScript types: /sdk/v1/quickshop.d.ts.

The store's own Supabase

For data beyond products and orders (bookings, sign-ups, members, a blog), the owner connects their Supabase project under Own website → Database. Pages hosted by QuickShop then get its public address and key; the database connection string stays encrypted on QuickShop's side and never reaches a page. Database changes live in the project as supabase/migrations/YYYYMMDDHHMMSS_name.sql: QuickShop runs the waiting ones when the owner approves them, each in one transaction, recorded in quickshop.migrations (or hands over one SQL script to run in Supabase). A change never runs twice. The owner can also have every order copied into public.quickshop_orders (row level security on, no public access), and sync products from one of the project's tables.

import { createClient } from "@supabase/supabase-js";

// null when the store hasn't connected its Supabase
const { url, anonKey } = QuickShop.supabase;
const supabase = createClient(url, anonKey);
await supabase.from("bookings").insert({ name, day });

Your own backend

Keep the products in your own system (your own Supabase, an ERP, a till) and let QuickShop run the shop and the orders. Products are matched by externalId, your own id or SKU. New ones are created, changed ones updated, and with hideMissing the ones you no longer send are hidden (never deleted: past orders point at them). Categories are matched by name and made when new.

Push from your system

PUT https://quickshop-mr5u.onrender.com/api/v1/catalog
Authorization: Bearer qs_sk_key_with_catalog_write

{
  "hideMissing": true,
  "products": [
    {
      "externalId": "SKU-1042",
      "name": "Red velvet cake",
      "category": "Cakes",
      "price": 1350,
      "description": "Serves 8",
      "images": ["https://cdn.example.com/rv.jpg"],
      "stock": 4,                // null or left out: not counted (made to order)
      "available": true,
      "options": [{ "name": "Size", "choices": [{ "name": "Large", "priceDelta": 400 }] }]
    }
  ]
}

→ { "created": 1, "updated": 0, "unchanged": 0, "hidden": 0, "errors": [] }

Up to 2,000 products per request. A product that can't be used is skipped and listed in errors; the rest still sync. Images must be https addresses.

Or let QuickShop fetch it

On Developers → Sync products from your system, give an https address that answers the same JSON (or just the list), an optional header, and how often to fetch it. A Supabase table or view works as is: snake_case columns and the names id/sku, image_url, category_name, stock_quantity, is_available are understood.

Feed address:  https://<project>.supabase.co/rest/v1/products?select=*
Header:        apikey = <your Supabase anon key>

Orders back to your system

Subscribe a webhook to order.created, order.status_changed and order.payment_changed, or read GET /orders?createdAfter= with a secret key. Update orders with PATCH /orders/{id}/status. QuickShop stays the record of each order and its customer; your system is the record of the products.

Webhooks

Add your server's https:// address on the Developers page and pick events. QuickShop sends a POST with a JSON body for each one.

  • order.created · Someone placed an order
  • order.status_changed · Confirmed, Preparing, Ready, Completed or Cancelled
  • order.payment_changed · Customer says they paid, or you marked it paid or not received
  • enquiry.created · A question or visit request (enquire stores)
  • ping · Sent by “Send test”
POST /your/webhook
QuickShop-Event: order.status_changed
QuickShop-Delivery: 5f0c…        (this delivery)
QuickShop-Signature: t=1793606400,v1=6a3f…

{
  "id": "a1b2…",                 // the event: the same on every retry
  "type": "order.status_changed",
  "createdAt": "2026-11-02T10:15:00Z",
  "storeId": "…",
  "data": { "order": { "id": "…", "number": "QS-1042", "status": "Ready", … }, "change": "Ready" }
}

Check the signature

Every delivery is signed with your endpoint's secret (whsec_…). Compute an HMAC-SHA256 of {t}.{raw body} and compare it with v1. Refuse anything that doesn't match, or whose t is more than 5 minutes old.

import crypto from "node:crypto";

function isFromQuickShop(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex"));
  const given = Buffer.from(parts.v1 ?? "");
  return given.length === expected.length && crypto.timingSafeEqual(expected, given);
}

Answering and retries

Answer with any 2xx within 10 seconds; do slow work afterwards. Otherwise QuickShop tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. Events can arrive more than once or out of order: use id to skip repeats and the order's own status as the truth. An endpoint that fails for 3 days straight is switched off and the owner is alerted. Redirects are not followed.

Errors and limits

HTTP/1.1 403
{ "error": { "code": "insufficient_scope", "message": "This key doesn't have the \"orders:read\" scope…" } }
400invalid_requestSomething in the request needs fixing; the message says what
401missing_api_key / invalid_api_keyNo key, a revoked key, or the store is suspended
403insufficient_scopeThe key isn't allowed to do this
404not_foundNothing with that id in this store
429rate_limitedToo many requests; wait for the Retry-After seconds

Limits per minute: secret keys 120 requests; publishable keys 60 per visitor and 1,200 in total.

Questions? Email quickshop@gmail.com. Store owners: make a key.