Klarity Storefront API

Authentication

Send your key as a Bearer token.

Copy# curl
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/products-by-category/snacks?limit=4"

Conventions

Shared rules for parameters, formats, and response envelopes across the API.

Barcode

Create barcode images for labels and printing from EAN, ISBN, or SKU.

Examples

Copy# EAN (auto)
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "ean":"6001234567890" }' \
     "https://api.myklarity.store/v1/barcode"

Copy# SKU (Code128)
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "source":"sku", "format":"code128", "sku":"SKU-1001" }' \
     "https://api.myklarity.store/v1/barcode"

Copy# Response
{
  "ok": true,
  "image": "barcode_42_ean13_6001234567890.png",
  "format": "ean13",
  "value": "6001234567890"
}

Quickstart

A minimal request/response to validate auth and see the API shape.

Fetch four items from a category.

CopyGET https://api.myklarity.store/v1/products-by-category/snacks?limit=4
Authorization: Bearer YOUR_API_KEY

200 OK
{
  "ok": true,
  "data": [
    {
      "id": 501,
      "handle": "crunchy-bites",
      "sku": "CRN-501",
      "title": "Crunchy Bites",
      "description": "Small bag, big crunch.",
      "price": "22.98",
      "price_cents": 2298,
      "currency": "GBP",
      "currency_symbol": "GBP",
      "price_formatted": "GBP 22.98",
      "image": "https://cdn.mystockly.store/client/your-tenant/products/p-501.jpg",
      "qty_on_hand": 20,
      "qty_reserved": 6,
      "qty_available": 14,
      "categories": [
        { "id": 10, "slug": "snacks", "title": "Snacks" }
      ],
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "total": 1
}

Products

Read product catalog data for storefronts, apps, and reporting.

Examples

Copy# Single product by handle
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/product/sea-salt-chips"

Copy# Products by location
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/products?loc=MAIN&include_stock_by_loc=1"

Copy# Filtered list (include categories + price range)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/products-all?include_category=chocolate,sweets&min_price_cents=1000&max_price_cents=3000&sort=price_asc"

Copy# Search (title/description)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/search/products?q=caramel&page=1&limit=6"

Categories

Browse category structures and fetch their product groupings.

Examples

Copy# Category details
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/category/snacks"

Copy# Category listing, page 2, 12 per page, highest price first
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/products-by-category/snacks?page=2&limit=12&sort=price_desc"

Collections

Work with curated collections for merchandising and navigation.

Examples

Copy# Collection listing (newest first)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/products-by-collection/gifts?limit=8&sort=newest"

Images & Assets

Retrieve image and asset metadata for product and content displays.

Resolve image IDs into full URLs (plus slug and alt text) via single or batch lookups.

CopyGET /v1/assets?ids=42,99

200 OK
{
  "ok": true,
  "data": [
    { "id": 42, "url": "https://cdn.mystockly.store/client/<tenant>/assets/42.jpg", "slug": "classic-tee-blue", "alt": "Classic Tee - Blue" },
    { "id": 99, "url": "https://cdn.mystockly.store/client/<tenant>/assets/99.jpg", "slug": "eco-tote", "alt": "Eco Tote (reusable)" }
  ]
}

Orders

Read orders, line items, and fulfilment state for customer workflows.

Examples

Copy# List orders with items
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/orders?limit=20&include_items=1"

Copy# Create an order
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "order_ref":"WEB-1001", "currency":"GBP", "items":[{"product_id":110,"name":"Item","qty":1,"price":9.99}], "payments":[{"method":"card","amount":9.99,"status":"paid"}] }' \
     "https://api.myklarity.store/v1/new-order"

Users

Manage staff users and permissions.

Example

Copy# Create a user
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "first_name":"Ava", "last_name":"Wells", "email_address":"ava@example.com", "useradmin":0, "user_active":1, "permissions":{"orders":1,"inventory":1} }' \
     "https://api.myklarity.store/v1/users"

Inventory (GET & POST)

Inventory operations including locations, stocktakes, transfers, and purchasing.

Server-side reads and writes for multi-location stock. Endpoints are grouped by domain for clarity.

Locations

Create and manage stock locations used across transfers and reporting.

Examples

Copy# List locations
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/locations?status=active"

Copy# Dry-run archive
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/locations/3/dry-run-archive?user=18"

Copy# Archive a location
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/locations/3/archive"

Stocktakes

Create and review stocktake batches and their counted lines.

Transfers

Move stock between locations and track transfer status.

Examples

Copy# Create a transfer WHS -> MAIN
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "from_location_id":2, "to_location_id":1, "product_id":110, "qty":10, "note":"Restock" }' \
     "https://api.myklarity.store/v1/inventory/create-transfer"

Copy# Receive a pending transfer line
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "transfer_id":501, "transfer_line_id":1, "qty":5 }' \
     "https://api.myklarity.store/v1/inventory/receipt-transfer"

Ops Flags

Dashboard-ready summaries for operational attention and prioritisation.

Example response

Example request

Copy# Ops flags for MAIN, weekly window
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/inventory/ops-flags?loc=MAIN&period=week"

Copy# Ops flags for all locations, monthly window
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/inventory/ops-flags?period=month"

Copy{
  "ok": true,
  "stocktake_locks": [],
  "pending_orders": { "total": 12 },
  "pending_transfers": { "total": 3, "items": [ { "risk": "high" } ] },
  "pending_transfer_orders": { "total": 1 },
  "prod_replens": { "total": 5 },
  "open_pos": { "total": 2, "units_open": 140 },
  "overdue_pos": { "total": 1 },
  "top_locations": {
    "period_days": 14,
    "items": [ { "location_id": 1, "code": "MAIN", "orders": 22, "total": 15420.50 } ]
  },
  "top_channels": {
    "period_days": 14,
    "items": [ { "channel": "online", "orders": 18, "total": 12010.00 } ]
  }
}

Status

Update status for transfers and purchase orders.

Examples

Copy# Update status: transfer -> in_transit
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "type":"transfer", "id":702, "from_location":"WHS", "to_location":"MAIN", "status":"in_transit" }' \
     "https://api.myklarity.store/v1/inventory/status"

Copy# Update status: purchase order -> approved
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "type":"purchase-order", "id":301, "reference":"PO-301", "status":"approved" }' \
     "https://api.myklarity.store/v1/inventory/status"

Purchase Orders

Create, retrieve, and update purchase orders and their lines.

Examples

Copy# Find PO lines by reference + delivery note
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/inventory/purchase-orders/find?reference=PO-001&delivery_note=DN-888&location_id=1"

Copy# Receipt PO lines (GRN)
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "id":123, "reference":"PO-001", "lines":[{"line_id":7,"qty":5},{"line_id":8,"qty":2}], "grn":"GRN-009", "delivery_note":"DN-888", "note":"partial receipt" }' \
     "https://api.myklarity.store/v1/inventory/purchase-orders/receive"

Copy# Attach ASN metadata
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "id":123, "asn":"ASN-889", "delivery_note":"DN-888", "external_ref":"ERP-42" }' \
     "https://api.myklarity.store/v1/inventory/purchase-orders/attach-asn"

Copy# Update PO fields
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "id":123, "reference":"PO-001", "supplier_id":77, "expected_date":"2025/11/20", "status":"open", "note":"ETA confirmed" }' \
     "https://api.myklarity.store/v1/inventory/purchase-orders/update"

Suppliers

List supplier records used on purchase orders.

Products (Lookup)

Lookup products for inventory workflows such as transfers and receipts.

Levels

Read per-location stock levels and availability.

Examples

Copy# Levels for a location (all products)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/inventory/levels?loc=MAIN"

Copy# Levels for a location and a single product
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/inventory/levels?loc=MAIN&product=110"

Receipts

List inventory receipts and inbound stock history.

Examples

Copy# Receipts for a location
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.myklarity.store/v1/inventory/receipts?loc=MAIN"

Adjustments

Track manual adjustments to inventory levels.

Examples

Copy# Adjustment (stock take)
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{ "location_id":1, "product_id":110, "qty":-2, "reason":"stock_take", "note":"Counted" }' \
     "https://api.myklarity.store/v1/inventory/adjust"

Audit

Audit trail of inventory changes by product and location.

POS Terminals

Endpoints for managing POS terminals, user profiles, PINs, assignments, and terminal activity.

Admin endpoints require API key auth. POS sessions use the token issued by /v1/pos/auth.

Authentication

Terminals

User Profiles

PINs

Assignments

Examples

Copy# POS login
curl -X POST -H "Content-Type: application/json" \
     -d '{ "till":"till-01", "password":"secret", "company":"acme" }' \
     "https://api.myklarity.store/v1/pos/auth"

Copy# Refresh token with master pin
curl -X POST -H "Content-Type: application/json" -H "X-POS-Token: CURRENT_TOKEN" \
     -d '{ "masterPin":"1234" }' \
     "https://api.myklarity.store/v1/pos/auth"

Pagination & Sorting

Use paging and sorting parameters for list endpoints.

• Pagination: page (1-based), limit (1-60). Defaults vary by endpoint (commonly 24).
• Sorting: sort=newest|price_asc|price_desc (where supported).

Copy# Top 4 newest items in "drinks"
GET /v1/products-by-category/drinks?limit=4&sort=newest

Debugging pagination

Quick checks when results look incomplete.

Error Model

Errors include an HTTP status and a short machine-readable code.

Copy401 Unauthorized
{
  "ok": false,
  "error": "unauthorized",
  "hint": "invalid_api_key"
}

404 Not Found
{
  "ok": false,
  "error": "not_found"
}

405 Method Not Allowed
{
  "ok": false,
  "error": "method_not_allowed"
}

CORS & Preflight

How browsers should preflight and access the API from web apps.

Allowed origins reflect https://*.myklarity.store. Preflight (OPTIONS) returns 204 with:

CopyAccess-Control-Allow-Origin: https://<sub>.myklarity.store
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

API Roadmap

Planned improvements and upcoming capabilities.

• Webhook Notifications for inventory updates and price changes.
• Batch Endpoints (e.g., multiple handles in one request).
• Variant/Options API with SKU-level availability.
• Expanded Search (full-text and suggestions).
• Rate Limit Headers for proactive client handling.
• Signed Media URLs for private asset delivery.