Skip to content

Canonical Contracts

These are the core entities and events the platform should standardize on.

Entity: Catalog Item

{
  "itemId": "item_01JQX3QG7MV8V7P4QZ0N8Y2J8W",
  "tenantId": "tenant_aierp",
  "type": "physical_product",
  "title": "Amul Taaza Milk 1 L",
  "subtitle": "Toned milk",
  "brand": "Amul",
  "categoryPath": ["Dairy", "Milk"],
  "unit": {
    "value": 1,
    "measure": "L"
  },
  "images": [
    {
      "url": "https://cdn.example.com/catalog/items/item_01/front.jpg",
      "kind": "primary"
    }
  ],
  "attributes": {
    "veg": true,
    "taxCode": "GST_5",
    "shelfLifeDays": 3
  },
  "status": "active",
  "version": 12,
  "updatedAt": "2026-03-25T02:30:00Z"
}

Entity: Menu Item

{
  "menuItemId": "menu_01JQX3T19Q88W4S3YJS6TRR6D3",
  "tenantId": "tenant_aierp",
  "merchantId": "merchant_restaurant_001",
  "storeId": "store_koramangala_01",
  "title": "Paneer Roll",
  "description": "Fresh paneer filling with mint chutney",
  "baseItemId": "item_01JQX3QG7MV8V7P4QZ0N8Y2J8W",
  "categoryId": "cat_rolls",
  "price": {
    "currency": "INR",
    "amount": 12900
  },
  "availability": {
    "status": "in_stock",
    "isOrderable": true
  },
  "addons": [
    {
      "groupId": "addon_extra_cheese",
      "min": 0,
      "max": 1
    }
  ],
  "version": 7
}

Entity: Inventory Position

{
  "itemId": "item_01JQX3QG7MV8V7P4QZ0N8Y2J8W",
  "storeId": "darkstore_blr_hsr_07",
  "onHand": 42,
  "reserved": 3,
  "availableToSell": 39,
  "status": "orderable",
  "updatedAt": "2026-03-25T02:31:04Z",
  "source": {
    "provider": "unicommerce",
    "sourceItemId": "SKU-AML-MILK-1L"
  }
}

Entity: Price Book Entry

{
  "priceId": "price_01JQX3W8P62S9P5A9A6ATY4Y4W",
  "itemId": "item_01JQX3QG7MV8V7P4QZ0N8Y2J8W",
  "storeId": "darkstore_blr_hsr_07",
  "currency": "INR",
  "mrp": 7000,
  "sellingPrice": 6500,
  "effectiveFrom": "2026-03-25T00:00:00Z",
  "taxCode": "GST_5",
  "version": 15
}

Entity: Dark Store Assortment

{
  "storeId": "darkstore_blr_hsr_07",
  "itemId": "item_01JQX3QG7MV8V7P4QZ0N8Y2J8W",
  "isListed": true,
  "isSearchable": true,
  "isOrderable": true,
  "shelfSlot": "A-12-03",
  "pickerPriority": 18,
  "updatedAt": "2026-03-25T02:30:44Z"
}

Event: Catalog Item Updated

Topic:

  • catalog.events
{
  "eventId": "evt_01JQX403S2G2D8E5TQ80P22VHF",
  "eventType": "catalog.item.updated",
  "tenantId": "tenant_aierp",
  "occurredAt": "2026-03-25T02:30:00Z",
  "source": {
    "provider": "petpooja",
    "sourceEventId": "pp_evt_99818"
  },
  "payload": {
    "itemId": "item_01JQX3QG7MV8V7P4QZ0N8Y2J8W",
    "version": 12
  }
}

Event: Inventory Stock Changed

Topic:

  • inventory.events
{
  "eventId": "evt_01JQX40G2WZKVH8Z0RTSYQ6Y8J",
  "eventType": "inventory.stock.changed",
  "tenantId": "tenant_aierp",
  "occurredAt": "2026-03-25T02:31:04Z",
  "payload": {
    "itemId": "item_01JQX3QG7MV8V7P4QZ0N8Y2J8W",
    "storeId": "darkstore_blr_hsr_07",
    "delta": -4,
    "onHand": 42,
    "reserved": 3,
    "availableToSell": 39
  }
}

Event: Store Status Changed

Topic:

  • store-status.events
{
  "eventId": "evt_01JQX41GNM7B0T7P8W9SS4SRG2",
  "eventType": "store.status.changed",
  "tenantId": "tenant_aierp",
  "occurredAt": "2026-03-25T02:32:18Z",
  "payload": {
    "storeId": "store_koramangala_01",
    "status": "busy",
    "acceptingOrders": true,
    "estimatedPreparationMins": 18
  }
}

API Contracts for the UI

List catalog for a store

GET /v1/stores/:storeId/catalog?category=Dairy&cursor=...

Response:

{
  "items": [
    {
      "itemId": "item_01JQX3QG7MV8V7P4QZ0N8Y2J8W",
      "title": "Amul Taaza Milk 1 L",
      "price": 6500,
      "currency": "INR",
      "availability": "orderable",
      "imageUrl": "https://cdn.example.com/catalog/items/item_01/front.jpg"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjIwfQ=="
}

GET /v1/stores/:storeId/search?q=milk

Inventory summary for POS

GET /v1/stores/:storeId/inventory?itemIds=item_1,item_2

Recommendations

GET /v1/stores/:storeId/recommendations?context=item&itemId=item_1

Contract Rules

Versioning

  • every mutable entity carries a monotonically increasing version
  • downstream consumers should ignore stale versions

Money

  • represent money in minor units
  • use integers, not floating point

Idempotency

  • each event must carry a unique eventId
  • provider-specific sourceEventId should be preserved when available

Time

  • all service contracts should use UTC ISO-8601 timestamps

Multi-tenancy

  • every event and entity must carry tenantId

Frontend Integration Notes

This POS UI repo can later consume these contracts by:

  • replacing demo products with /v1/stores/:storeId/catalog
  • replacing local cart availability with /v1/stores/:storeId/inventory
  • calling /v1/stores/:storeId/search
  • showing real-time stock changes via SSE / WebSocket fed from inventory events