Getting Started1 min read

Quick Start: First Metered API Call in 10 Minutes

Get from zero to your first metered API call using the Aforo Node.js SDK. No gateway required to start.

Docs  Getting Started  Quick Start

Prerequisites#

Before you begin, make sure you have the following ready. The entire flow takes under 10 minutes on a clean machine.

Node.js 18+

Required by the SDK. Check: node --version

Aforo Account

Sign up for an Aforo account — free sandbox included

API Key

sk_test_… from Admin Panel → API Keys

Product + Metric

Any product with at least one billable unit configured

 PRO TIP

You do not need a gateway plugin to start. The Node.js SDK sends events directly to Aforo's ingest endpoint. Deploy the gateway plugin later when you're ready to go to production.

Install SDK or Plugin#

Install the Aforo metering SDK into your project. The SDK handles batching, retries, and async flushing so your API latency is never impacted.

terminal

npm install @aforo/metering

If you use Yarn or pnpm, the package name is the same:

terminal

# Yarn
yarn add @aforo/metering

# pnpm
pnpm add @aforo/metering

Initialize the Client

Create a single client instance and reuse it across your application. The client batches events internally and flushes every 5 seconds or when the buffer reaches 100 events — whichever comes first.

aforo-client.ts

import { AforoClient } from '@aforo/metering';

export const aforo = new AforoClient({
  apiKey: process.env.AFORO_API_KEY!,   // sk_test_… or sk_live_…
  productId: process.env.AFORO_PRODUCT_ID!,
  // Optional — defaults to https://ingest.aforo.ai
  // ingestUrl: 'https://ingest.aforo.ai',
});

 INFO

Store your API key in an environment variable — never hardcode it. The SDK reads process.env.AFORO_API_KEY automatically if you skip the apiKey option.

Fire Your First Event#

Call aforo.meter() anywhere in your request handler, background job, or webhook processor. The call is non-blocking — it returns immediately and the SDK queues the event for async delivery.

api-handler.ts

import { aforo } from './aforo-client';

export async function handleSearchRequest(req: Request) {
  const customerId = req.headers.get('X-Customer-Id')!;

  // Your existing business logic — unchanged
  const results = await runSearch(req.body.query);

  // Fire the meter event — non-blocking, async
  await aforo.meter({
    customerId,                        // Maps to an Aforo customer record
    metricId: 'api_calls',             // Billable unit ID from your dashboard
    quantity: 1,
    properties: {
      endpoint: '/v1/search',
      statusCode: 200,
      latencyMs: results.latencyMs,
    },
  });

  return Response.json(results.data);
}

Full Working Example (standalone script)

If you want to test without wiring into your application, pick your language and run this script directly. It fires a single meter event and waits for the flush to confirm delivery.

test-meter.ts

import { AforoClient } from '@aforo/metering';

const aforo = new AforoClient({
  apiKey: 'sk_test_YOUR_KEY_HERE',
  productId: 'YOUR_PRODUCT_ID',
});

async function main() {
  console.log('Firing test meter event...');

  await aforo.meter({
    customerId: 'cust_test_001',
    metricId: 'api_calls',
    quantity: 1,
    properties: { source: 'quick-start-test' },
  });

  // Flush ensures the event is delivered before the process exits
  await aforo.flush();

  console.log('Event delivered. Check your Aforo dashboard.');
}

main().catch(console.error);

terminal

# Run the test script
npx tsx test-meter.ts

# Expected output:
# Firing test meter event...
# Event delivered. Check your Aforo dashboard.

 PRO TIP

The SDK buffers events and sends them in batches. Calling await aforo.flush() forces immediate delivery — useful in scripts, serverless functions, and test suites where the process exits before the automatic flush interval.

Verify in Dashboard#

After running the script, open your Aforo Admin Panel to confirm the event was received and rated correctly.

Open Admin Panel

Filter by Customer

Search for cust_test_001 — your test event appears within 5 seconds

Inspect the Event

Click the row to see the full payload: metric, quantity, properties, rated amount

Check Usage Ledger

Customers → cust_test_001 → Usage tab shows accumulated metered usage

 INFO

Events appear in the Event Log within 5 seconds of delivery. Rating (converting raw events to dollar amounts based on your rate plan) happens asynchronously and is reflected in the Usage tab within 30 seconds.

Next Steps#

You have successfully fired your first metered event. From here, choose the path that fits your stack.