TinyCommerce
Headless Commerce Engine

Build any storefront with Tiny Commerce API.

Completely frontend-agnostic. 100% store-scoped authentication.

Craft bespoke shopping experiences on Next.js, Remix, Astro, Vue, or native mobile apps. Tiny Commerce powers your catalog, real-time inventory, ACID checkout transactions, and store operations.

Quick Start • cURL
curl -X GET https://api.malicc.com/v1/products \ -H "Authorization: Bearer pk_live_sampleKey123" \ -H "Accept: application/json"

Enterprise-Grade API Authentication

Designed after the Stripe and Shopify credential architectures for maximum developer simplicity and multi-tenant security.

Browser Safe

Publishable Keys (pk_...)

Safe for browser & client bundles. Scoped strictly to public catalog reads, variant details, and customer cart initiation.

Server-Side Only

Secret Keys (sk_...)

Kept in secure server environments (.env). Authorized for elevated order lookups, inventory updates, and privileged mutations.

Zero-Trust

Strict Tenant Isolation

Tenant store context is cryptographically derived from the verified API key hash. Clients never pass arbitrary store IDs as authority.

Instant Security

Rotation & Revocation

Zero-downtime key rotation. Old keys are immediately invalidated and newly hashed secrets are returned only once at creation.

Integration Quickstart

Plug and play with your preferred environment.

storefront-api.ts
// 1. Fetch published store products in Next.js / React
export async function getStoreProducts() {
  const response = await fetch("https://api.malicc.com/v1/products?limit=12", {
    headers: {
      "Authorization": `Bearer ${process.env.NEXT_PUBLIC_MALICC_PUBLISHABLE_KEY}`,
      "Accept": "application/json",
    },
    next: { revalidate: 60 } // Next.js ISR cache
  });

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(errorData.error?.message || "Failed to fetch catalog");
  }

  const { data, pagination } = await response.json();
  return { products: data, pagination };
}

Granular Permission Scopes

Enforce the principle of least privilege. Assign only the specific scopes your integration requires.

Scope IdentifierDescriptionBrowser (pk_...)Server (sk_...)
store:read

Read store metadata, currency, social links, theme configuration, and store status.

Target: Public storefront layout & branding hydration
Allowed Allowed
categories:read

Query store product collections, taxonomy categories, slugs, and navigation trees.

Target: Category grids, header navigation, collection filtering
Allowed Allowed
products:read

Query published catalog listings, category hierarchy, variants, prices, and stock levels.

Target: Storefront product pages, search, and category grids
Allowed Allowed
products:write

Create new products, modify price points, update inventories, or archive catalog items.

Target: ERP/PIM inventory sync scripts, warehouse automation
Blocked Allowed
carts:manage

Create carts, add/update/remove line items, calculate totals, and initiate checkout sessions.

Target: Headless shopping bag, checkout initiation, cart drawer
Allowed Allowed
orders:read

Query store order histories, customer transactions, payment timestamps, and fulfillment states.

Target: Fulfillment apps, custom reporting dashboards
Blocked Allowed
orders:write

Update order fulfillment statuses, tracking numbers, or process returns and notes.

Target: Shipping carrier integrations, warehouse dispatch bots
Blocked Allowed

Available Headless API Endpoints

Stateless REST endpoints hosted at https://api.malicc.com/v1.

Store Configuration

store:read

Hydrate branding assets, supported currencies, contact details, and theme settings.

GET/v1/store

Retrieve active store identity & theme JSON

Categories

categories:read

List and inspect published store collections and category hierarchies.

GET/v1/categories

List all store categories with product counts

GET/v1/categories/:id

Retrieve specific category details

Products & Catalog

products:read

Query and paginate published store products, category filters, and live stock levels.

GET/v1/products

List catalog with ?category_id & pagination

GET/v1/products/:id

Retrieve single product with details

Headless Carts

carts:manage (pk_)

Manage client carts with server-authoritative pricing and X-Malicc-Cart-Token protection.

POST/v1/carts

Create a cart & receive cart access token

GET/v1/carts/:id

Fetch cart totals & line items

POST/v1/carts/:id/items

Add item with server stock check

PATCH/v1/carts/:id/items/:itemId

Update item quantity

DELETE/v1/carts/:id/items/:itemId

Remove item from cart

Checkouts & Payment Sessions

products:read (pk_)

ACID checkout transitions, Razorpay sessions, and idempotency safeguards.

POST/v1/checkouts

Initiate checkout from cart & get Razorpay order

POST/v1/checkouts/payment-sessions/verify

Cryptographically verify payment session

Orders & Fulfillment

orders:read (sk_)

Privileged server-side inquiry into store order pipelines and payments.

GET/v1/orders

List merchant store orders with filters

GET/v1/orders/:id

Retrieve single order transaction details

Full API Contract Blueprint & Specs

Read complete details on cursor pagination, cart tokens, payment sessions, idempotency headers, and rate limiting in the Docusaurus documentation.

Get API Keys