API Reference

Kadaikodi is API-first: every capability is reachable through a single GraphQL API over HTTPS. Build any storefront, kiosk, or agent on top of cart, catalog, order, merchant, and fulfillment operations.

How the API works

• Single GraphQL endpoint — commerce operations and shared platform capabilities are reachable from one graph
• Permission-checked — every query and mutation is authorized against the calling actor's role before it executes
• Authentication — OAuth device-code login for CLIs and apps; OAuth client credentials for service-to-service integrations
• Multi-tenant — every entity is workspace-scoped, so callers only ever see their own workspace's data

Core entities

The GraphQL graph is built on Kadaikodi's domain objects:

Entity	Description
Merchant (ServiceProvider)	A seller — brand, store, supplier, or operator — with category, offering type, lifecycle status, branding, hours, verification, and rating
Offering	A sellable product (with stock) or service (with duration), unified under one model
Cart	A durable, headless working set of offerings with quantities, customizations, and computed totals
Order / Order Item	The single source of truth for a transaction, with an independent payment-status machine and a timeline
Worker / Worker Task	Fulfillment rosters and discrete dispatch jobs
Review	Customer feedback tied to a merchant and order
Investment Opportunity / Investment	Merchant financing with an auditable transaction ledger
Configuration	Platform / merchant / user scoped settings

Catalog & offerings

# Create an offering (product or service)
mutation {
  createOffering(input: {
    name: "Cold Brew Coffee"
    category: FOOD_AND_BEVERAGE
    price: 180.00
    compareAtPrice: 220.00
    stock: 40
    fulfillmentTypes: [PICKUP, DELIVERY]
  }) {
    id
    name
    slug
    price
  }
}

# Update an offering
mutation {
  updateOffering(id: "off_123", input: { price: 160.00, available: true }) {
    id
    price
    available
  }
}

Cart & checkout

# Place an order from a cart, with server-computed pricing
mutation {
  placeOrder(input: {
    items: [{ offeringId: "off_123", quantity: 2, customizations: ["No sugar"] }]
    fulfillmentType: DELIVERY
    deliveryAddress: "..."
    paymentMethod: UPI
  }) {
    id
    orderNumber
    status
    paymentStatus
    subtotal
    tax
    deliveryFee
    discount
    total
  }
}

Orders & lifecycle

# Advance an order through its lifecycle (records a timeline entry)
mutation {
  updateOrderStatus(id: "ord_789", status: PREPARING) {
    id
    orderNumber
    status      # pending → placed → confirmed → preparing → ready → out_for_delivery → delivered → completed
    paymentStatus
  }
}

Merchant management

# Onboard a merchant (service provider)
mutation {
  kadaikodiCreateServiceProvider(input: {
    name: "Anbu's Kitchen"
    category: FOOD_AND_BEVERAGE
    offeringType: BOTH
  }) {
    id
    name
    status      # draft → active → verified → paused → suspended → archived
  }
}

# Update a merchant
mutation {
  kadaikodiUpdateServiceProvider(id: "mer_42", input: { status: VERIFIED }) {
    id
    status
  }
}

Fulfillment & workers

# List a merchant's workers
query {
  listProviderWorkers(providerId: "mer_42") {
    id
    role
    status
  }
}

# List worker tasks
query {
  listWorkerTasks(providerId: "mer_42") {
    id
    type       # delivery | pickup | service | inventory | cleanup
    status     # assigned → in_progress → blocked → completed → cancelled
    priority
    orderId
  }
}

Reviews & financing

# Create a review
mutation {
  createReview(input: { merchantId: "mer_42", orderId: "ord_789", rating: 5, feedback: "Great!" }) {
    id
    rating
  }
}

# Respond to a review (merchant)
mutation { respondToReview(id: "rev_1", response: "Thank you!") { id } }

# Publish an investment opportunity
mutation {
  createInvestmentOpportunity(input: {
    targetAmount: 500000
    minimumInvestment: 5000
    expectedReturns: "..."
    lockInPeriod: "..."
    riskLevel: MEDIUM
  }) { id raisedAmount targetAmount }
}

# Invest in an opportunity
mutation { invest(opportunityId: "opp_5", amount: 10000) { id currentValue } }

Analytics

# Workspace dashboard
query {
  kadaikodiDashboardStats {
    totalOrders
    totalRevenue
    activeMerchants
    activeCustomers
    averageRating
    pendingOrders
  }
}

# Admin analytics
query {
  kadaikodiAdminAnalytics {
    revenueByCategory { category revenue }
    orderTrends { date count }
    topMerchants { merchantId revenue }
    customerGrowth { date count }
  }
}

Surfaces

The same graph backs every client. Mobile, CLI, MCP, SDKs, and extensions are part of the launch surface plan and roll out progressively.

• Headless GraphQL API — the integration substrate (available)
• Node.js / Python SDKs — typed access over the same operations **
• CLI / MCP server — automation and AI-agent access **

---

Field names and arguments follow the published GraphQL schema; treat the published schema as the authoritative source as the API reaches general availability.