Getting Started1 min read

Edge-to-Ledger: Kong to NetSuite Lifecycle

The complete journey of a billable event — from gateway interception through the 10-stage pipeline to a finalized NetSuite invoice.

Docs  Guides  Kong to NetSuite

The Three Phases#

Every dollar of usage-based revenue passes through three distinct phases. Understanding this lifecycle is the difference between a billing system and a revenue engine.

1

THE EDGE

Kong Gateway

Intercept, authenticate, and check entitlements in <2ms

2

THE BRAIN

Aforo Engine

Validate, rate, discount, tax, and settle through 10 stages

3

THE BOOKS

NetSuite ERP

Finalized invoice synced with idempotent dedup — zero double-billing

Phase 1: The Edge (Kong Gateway)#

JIRA-READY TASK

Enable the Aforo metering sidecar on Kong. Verify entitlement cache is warm before enabling margin enforcement.

Estimated time: 15 minutes. Target: Platform Engineer.

When an API request hits Kong, the Aforo plugin executes two operations before the request reaches your upstream:

<2ms

Edge Entitlement Check

Local Redis lookup. No cross-network call. No impact on P99.

1. Entitlement Check (Access Phase)

The plugin reads the tenant ID from the request header, looks up their subscription and quota from the local Redis cache, and makes an allow/deny decision. If the Margin Guard is in "strict" mode, it also checks the tenant's current margin percentage.

2. Usage Capture (Log Phase)

After the upstream response is returned to the client, the plugin fires an asynchronous usage event. This is the raw payload that enters the Aforo pipeline:

kong-to-aforo-payload.json

{
  "event_id": "evt_7f3a2b1c_1711756800",
  "tenant_id": "tenant_acme_corp",
  "metric_key": "api_calls",
  "quantity": 1,
  "timestamp": "2026-03-29T14:32:00.042Z",
  "source": "kong",
  "idempotency_key": "kong_req_abc123_1711756800042",
  "properties": {
    "route": "/v1/search",
    "method": "POST",
    "status_code": 200,
    "response_time_ms": 142,
    "consumer": "acme-prod-key",
    "gateway_node": "kong-worker-03"
  },
  "entitlement_result": {
    "allowed": true,
    "remaining_quota": 8419,
    "margin_status": "healthy",
    "margin_pct": 34.2,
    "plan": "enterprise"
  }
}

 PRO TIP

The idempotency_key is generated from the Kong request ID + timestamp. This key follows the event through every stage of the pipeline and into NetSuite — guaranteeing exactly-once billing even if the event is retried.

Phase 2: The Brain (Aforo Engine)#

The raw event from Kong enters the Aforo Metering Engine, where it is validated, deduplicated, enriched, and then handed to the Billing Engine's 10-stage pipeline.

The 10-Stage Billing Pipeline#

Every billable event passes through all 10 stages sequentially. Each stage is deterministic, auditable, and idempotent:

1

Quota Check

Verify the tenant has not exceeded their allocated usage quota for this billing period.

2

Rollover

Apply any unused quota from the previous period if rollover is configured on the rate plan.

3

Aggregate

Sum all events for this metric + tenant + billing period into a running total.

4

Allowance

Subtract the free tier (includedFree units) from the aggregated total. Only overage is billable.

5

Rate

Apply the pricing model (Per Unit, Flat Rate, Percentage, Included Quota, Graduated, Volume Tiered) to calculate the raw charge.

6

Commit

Enforce minimum spend (true-up if actual < commit) and maximum spend cap (BLOCK or ALERT if exceeded).

7

Discount

Apply percentage or fixed-amount discounts. Capped at subtotal — charges never go negative.

8

Tax

Calculate tax via Vertex/Avalara integration. Computes total = subtotal - discount + tax.

9

Route

Direct the charge to the correct settlement path: POSTPAID → invoice, PREPAID → wallet drawdown, HYBRID → wallet first then invoice.

10

Settle

Finalize the invoice line item. Mark the event as settled. Publish to ERP sync queue.

MARGIN GUARD/ Pipeline Stage 6 (Commit)

If a tenant's accumulated charges hit the maximum spend cap during the Commit stage, the pipeline can either BLOCK (reject further events) or ALERT (notify the account manager and continue). This is the financial safety valve that prevents unbounded liability.

Idempotency: Zero Double-Billing#

The idempotency_key from Kong follows the event through every stage:

idempotency-chain.txt

Kong Plugin          → idempotency_key: kong_req_abc123_1711756800042
  ↓
Metering Engine      → Dedup check: key exists in Redis? NO → process
  ↓                    (if YES → skip, return 409 Duplicate)
Billing Pipeline     → Pipeline context tagged with idempotency_key
  ↓
Invoice Line Item    → line_item.source_event_id = kong_req_abc123_1711756800042
  ↓
NetSuite Sync        → externalId = kong_req_abc123_1711756800042
                       (NetSuite rejects if externalId already exists)

 INFO

Idempotency is enforced at three independent layers: Redis dedup at ingestion (TTL: 24hr), database unique constraint on event_id, and NetSuite externalId uniqueness. Even if all three retries succeed simultaneously, exactly one invoice line item is created.

Phase 3: The Books (NetSuite)#

After the Settle stage, the finalized invoice is published to the ERP sync queue. The NetSuite connector picks it up and creates the corresponding records:

netsuite-sync-payload.json

{
  "action": "CREATE_INVOICE",
  "externalId": "aforo_inv_2026_0412",
  "entity": {
    "internalId": "12345",
    "name": "Acme Corp"
  },
  "tranDate": "2026-03-31",
  "currency": "USD",
  "lineItems": [
    {
      "item": "Platform Fee (Enterprise)",
      "quantity": 1,
      "rate": 2000.00,
      "amount": 2000.00,
      "sourceEventId": "recurring_platform_fee_2026_03"
    },
    {
      "item": "API Usage (1,247,832 calls)",
      "quantity": 1247832,
      "rate": 0.004,
      "amount": 4991.33,
      "sourceEventId": "aggregated_api_calls_2026_03"
    },
    {
      "item": "Mid-Cycle Upgrade Proration",
      "quantity": 1,
      "rate": 603.00,
      "amount": 603.00,
      "sourceEventId": "proration_upgrade_2026_03_15"
    },
    {
      "item": "AI Token Overage (160K tokens)",
      "quantity": 160000,
      "rate": 0.006,
      "amount": 960.00,
      "sourceEventId": "overage_ai_tokens_2026_03"
    },
    {
      "item": "Negotiated Discount (15%)",
      "quantity": 1,
      "rate": -1283.15,
      "amount": -1283.15,
      "sourceEventId": "discount_enterprise_15pct"
    }
  ],
  "subtotal": 8554.33,
  "discount": -1283.15,
  "tax": 0.00,
  "total": 7271.18,
  "memo": "Auto-generated by Aforo Billing Engine v3. 10-stage pipeline. Idempotent."
}

0

Manual Data Entry

Every field auto-populated from pipeline output

0

Duplicate Invoices

externalId uniqueness enforced at NetSuite layer

<5min

Settle-to-Ledger

From pipeline completion to NetSuite record creation

CFO Note: Revenue Leakage Prevention#

CFO BRIEFING/ REVENUE ASSURANCE

The Kong-to-NetSuite pipeline eliminates the three primary sources of revenue leakage in usage-based billing:

Uncaptured Events: Every API request that passes through Kong is metered. The gateway plugin operates in the Lua log phase — it cannot be bypassed by the application. If Kong sees the request, Aforo captures it.

Manual Proration Errors: Mid-cycle upgrades, downgrades, and cancellations are calculated by the Billing Engine automatically. No spreadsheet, no manual adjustment, no human error. The math is deterministic and auditable.

Duplicate or Missing Invoices: The idempotency_key chain ensures exactly-once billing from gateway to ledger. NetSuite receives each invoice exactly once. The externalId constraint is the final safety net.

The estimated revenue recovery from eliminating these three leakage vectors is 3-5% of total usage-based revenue — typically $50K-$500K annually for a mid-market SaaS platform.

Next: API Reference