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
- The store owner opens Developers in the QuickShop dashboard and makes a key.
- Send it with every request:
Authorization: Bearer qs_… - 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
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.
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.
| Scope | Allows |
|---|---|
catalog:read | Products, categories, stock |
catalog:write | Add, change and delete products and categories |
orders:read | Every order, with the customer's phone |
orders:write | Place orders, change their status, mark them paid |
customers:read | Names, phones, order counts |
site:deploy | Publish your own website (e.g. from GitHub Actions) |
checkout | Quote 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
| Request | Scope | What it does |
|---|---|---|
GET/store | any key | The store: name, address, currency, fulfilment and payment options |
GET/categories | catalog:read | Categories |
POST/categories | catalog:write | Add a category { name } |
GET/products?category=&search= | catalog:read | Every product, with price, stock, options and photos |
GET/products/{id} | catalog:read | One product |
POST/products | catalog:write | Add a product (categoryId and name required) |
PATCH/products/{id} | catalog:write | Change only the fields you send, e.g. { price } or { stock } |
DELETE/products/{id} | catalog:write | Delete a product |
GET/delivery-zones | checkout | Where the store delivers, with fees (pass a zone's id as deliveryZoneId) |
POST/orders/quote | checkout | Exact total (promo code and delivery fee included) before ordering |
POST/orders | checkout | Place an order, with the same rules as the storefront |
GET/orders?status=&createdAfter=&limit=&cursor= | orders:read | Orders, newest first, 1–100 per page |
GET/orders/{id} | orders:read | One order |
PATCH/orders/{id}/status | orders:write | { status }: Confirmed, Preparing, Ready, Completed or Cancelled |
PATCH/orders/{id}/payment | orders:write | { paymentStatus }: Paid, or Pending (not received) |
GET/customers?limit=&cursor= | customers:read | Customers with order counts and totals |
PUT/catalog | catalog:write | Sync the whole catalog from your system, matched by externalId (see below) |
POST/site/deployments?note= | site:deploy | Deploy 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 orderorder.status_changed· Confirmed, Preparing, Ready, Completed or Cancelledorder.payment_changed· Customer says they paid, or you marked it paid or not receivedenquiry.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…" } }| 400 | invalid_request | Something in the request needs fixing; the message says what |
| 401 | missing_api_key / invalid_api_key | No key, a revoked key, or the store is suspended |
| 403 | insufficient_scope | The key isn't allowed to do this |
| 404 | not_found | Nothing with that id in this store |
| 429 | rate_limited | Too 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.