Developer Guide

Integration & API Guide

March 29, 2026

Publications

Two APIs, One Financial Engine

HedgeTech exposes two GraphQL APIs that share the same financial engine underneath:

Reporting API — read-only queries for dashboards, financial statements, analytics, and intelligence. Used by embedded apps, admin panels, and any system that needs to read financial state.
Profit Guard API — read + write mutations for processing transactions, managing settings, evaluating promotions, and governing financial operations. Used by Shopify webhooks, POS integrations, and external platforms.

Both APIs authenticate via JWT (issued by the vault service). Both return structured, typed responses. And both enforce the same financial rules — because they run on the same engine.

Executive Dashboard & Board Summary

query {
  executiveDashboard(input: {
    periodStart: "2026-01-01T00:00:00Z"
    periodEnd: "2026-03-31T23:59:59Z"
    waccBps: 850
  }) {
    totalRevenue
    totalLeakageDetected
    totalLeakagePrevented
    refundRiskIndexRate
    loyaltyLiabilityEstimate
    marketingEfficiencyRatioRate
    enterpriseValueDelta
  }
}

Returns KPIs across revenue, leakage, risk, and enterprise value for any date range. The boardSummary query provides a CFO-level view with severity distribution and strategic flags.

Financial Statements

query {
  profitAndLoss(input: {
    periodStart: "2026-01-01T00:00:00Z"
    periodEnd: "2026-03-31T23:59:59Z"
  }) {
    revenue { gross net discounts refunds }
    cogs { total shipping handling }
    grossProfit
    operatingExpenses { marketing loyalty fulfillment }
    netIncome
  }
}

Also available scoped by location (locationPnl), by SKU (skuPnl), or by sales channel (channelPnl). Plus workingCapital, cashFlowStatement, and dcfValuation queries.

Inventory & Customer Intelligence

query {
  inventoryFinancialSummary(input: {
    periodStart: "2026-01-01T00:00:00Z"
    periodEnd: "2026-03-31T23:59:59Z"
  }) {
    totalInventoryValue
    turnoverRate
    daysInventoryOutstanding
    deadStockValue
    shrinkageDetected
  }
}

customerEconomics returns lifetime value, acquisition cost, payback period, and churn risk per segment. sensitivityAnalysis and capitalAllocation provide what-if modelling.

Home Dashboard

query {
  computeDashboardHome(input: {
    periodStart: "2026-03-01T00:00:00Z"
    periodEnd: "2026-03-29T23:59:59Z"
  }) {
    financialSnapshot { ... }
    riskSnapshot { ... }
    inventorySnapshot { ... }
    governanceEffectiveness { ... }
    strategicSignals { ... }
    forwardRisk { ... }
  }
}

A single query that returns the entire home dashboard — financial snapshot, risk radar, inventory health, governance effectiveness, strategic signals, and forward risk assessment. One call, complete picture.

Profit Guard API — Mutations

The Profit Guard API processes every financial event as a validated mutation. Each mutation enforces business rules, generates journal entries, and updates projections atomically.

Processing a Shopify order:

mutation {
  processOrder(input: {
    orderId: "gid://shopify/Order/12345"
    lineItems: [{
      variantId: "gid://shopify/ProductVariant/99"
      quantity: 2
      price: { amount: 8999, currencyCode: AUD }
      cost: { amount: 3850, currencyCode: AUD }
    }]
    gatewayFees: [{ amount: 250, currencyCode: AUD }]
  }) {
    journalId
    grossMargin
    netMargin
  }
}

Processing a refund:

mutation {
  processRefund(input: {
    orderId: "gid://shopify/Order/12345"
    refundLineItems: [{
      variantId: "gid://shopify/ProductVariant/99"
      quantity: 1
      amount: { amount: 8999, currencyCode: AUD }
    }]
    reverseGatewayFees: true
  }) {
    journalId
    adjustedMargin
  }
}

PROMOTIONS

Evaluate a promotion before it goes live. Returns margin impact, stacking conflicts, and exposure limits. If the promotion fails financial validation, it is rejected before any customer sees it.

mutation { evaluatePromotions(input: { ... }) { approved marginImpact conflicts } }

OPERATIONS

Track chargebacks, reversals, inventory adjustments, cost revaluations, and fulfilment events. Each mutation generates double-entry journal pairs and maintains a complete audit trail.

mutation { processChargeback(input: { ... }) { journalId financialImpact } }
mutation { processInventoryAdjustment(input: { ... }) { adjustmentGid } }
mutation { processCostRevaluation(input: { ... }) { updatedCount } }

SETTINGS

Configure tax settings, fiscal year, accounting methods, WACC model, inflation parameters, and risk-free rates. Settings are versioned and auditable — changes are tracked as events.

mutation { upsertSettings(input: { ... }) { settingsId updatedAt } }
mutation { bootstrapSettings(input: { ... }) { settingsId } }

One Engine, Every Channel

Whether the request comes from a Shopify webhook, a POS terminal, an embedded Remix app, or a direct API call — it hits the same GraphQL schema, enforces the same rules, and produces the same deterministic result.

The Reporting API answers questions: What is my margin? Where is my risk? How is my inventory performing?

The Profit Guard API governs actions: Process this order. Evaluate this promotion. Adjust this inventory.

Together, they provide complete financial control over read and write operations. Every query is validated. Every mutation is enforced. Every result is auditable.

You Don’t Need Better Reporting. You Need Guaranteed Correctness.

Most systems show you what went wrong after the fact. HTQL guarantees correctness before execution. Every transaction validated. Every rule enforced. Every outcome deterministic. This is not analytics — this is control infrastructure.

Portal Login Create Account

Profit Guard Insights

Topic

The Leak You Don't See Is the One That Hurts Most

You don’t notice it at first. Sales are coming in. Customers are buying. Your dashboards look fine. Revenue is moving. Everything appears to be working. And yet, something feels off. Margins are tighter than expected. Cash doesn’t stretch as far as it should. Promotions feel like they’re “working”… but not delivering the financial outcome you assumed. This is where most merchants get it wrong. They think profit is lost in big decisions. **It isn’t.** It’s lost in small, repeated, invisible ones.

April 19, 2026

Topic

Discounts Don't Destroy Profit. Lack of Control Does

Discounts are powerful. They move inventory. They increase conversion. They create urgency. They reward customers. Used correctly, they accelerate growth. Used incorrectly, they destroy margin. **The difference is not the discount itself. It’s control.**

April 19, 2026

Topic

Inventory Is Not Stock. It's Capital at Risk

Most merchants think in units. How many items are in stock. How fast they are moving. How many are sold. But this is the wrong lens. Inventory is not stock. It is capital. **Locked capital. Allocated capital. At-risk capital.** Every unit sitting on a shelf represents money that is not working. Every unit in the wrong store represents missed opportunity. Every unit reserved unnecessarily represents blocked revenue.

April 19, 2026

Topic

Loyalty and Gift Cards: The Costs You Don't See Coming

They feel like assets. Loyalty programs build retention. Gift cards generate upfront cash. Customers engage more. Sales increase. On the surface, everything looks positive. But beneath that surface lies a financial reality most merchants ignore. **Loyalty is a liability. Gift cards are deferred obligations.** Every point issued is a future cost. Every gift card sold is revenue not yet earned.

April 19, 2026

Topic

The Moment Everything Changes

There is a moment every serious merchant experiences. It’s not loud. It’s not dramatic. But it is decisive. It’s the moment you realise: **the problem was never sales. It was control.** You were generating revenue. You were running promotions. You were moving inventory. But profit wasn’t following. Not consistently. Not predictably. And you couldn’t explain why.

April 19, 2026