Quick Start

Set up Scrawn usage-based billing in under a minute. Install the SDK, sync pricing tags, and start tracking billable events.

Install the SDK, sync your tags, and start tracking billable events.

1. Install

bun add @scrawn/core

npm install @scrawn/core

yarn add @scrawn/core

2. Configure

Create a scrawn.config.ts in your project root:

import { scrawnConfig } from "@scrawn/core";

export default scrawnConfig({
  apiKey: process.env.SCRAWN_KEY!,
  grpcUrl: process.env.SCRAWN_BASE_URL!,
  httpUrl: process.env.SCRAWN_HTTP_URL!,
  directory: "scrawn",
});

Add these to your .env.local or .env:

SCRAWN_KEY=scrn_live_abc123def456ghi789jkl012mno345pq
SCRAWN_BASE_URL=http://localhost:8069
SCRAWN_HTTP_URL=http://localhost:8070

If you are using Scrawn Cloud, sign up at app.scrawn.dev. Use https://api.scrawn.dev as both SCRAWN_BASE_URL and SCRAWN_HTTP_URL, and get your SCRAWN_KEY from app.scrawn.dev/dashboard/api-keys.

3. Sync tags & expressions

bunx scrawn tag sync

This generates scrawn/pricerefs.ts with your tags and expressions as compile-time checked types.

Every time you update tags or expressions on the dashboard, run bunx scrawn tag sync again to keep your types in sync.

4. Create your biller

// scrawn/biller.ts
import { scrawn } from "@scrawn/core";
import { TAGS, EXPRESSIONS } from "./pricerefs.ts";

export const biller = scrawn({
  apiKey: process.env.SCRAWN_KEY as string,
  baseURL: process.env.SCRAWN_BASE_URL as string,
  httpUrl: process.env.SCRAWN_HTTP_URL as string,
  tags: TAGS,
  expressions: EXPRESSIONS,
});

5. Track usage

Smallest currency unit - 250:

import { biller } from "./scrawn/biller";

await biller.basicUsageEventConsumer({
  userId: "user-123",
  debit: 250,
});

Or with a pricing expression:

import { biller } from "./scrawn/biller";
import { mul } from "@scrawn/core";

await biller.basicUsageEventConsumer({
  userId: "user-123",
  debit: biller.expr(mul(biller.tag("API_CALL"), 3)),
});

For middleware tracking, AI token billing, and framework adapters, check the usage tracking guide.

6. Collect payment

When a user's balance crosses your threshold, collect with one call:

const checkoutLink = await biller.collectPayment("user-123");
// → "http://localhost:3000/checkout/ses_abc123..."

No checkout URL manipulation needed - Scrawn creates the session, Scrawn proxies the link.