Autumn Billing

Overview

@kubiks/otel-autumn provides comprehensive OpenTelemetry instrumentation for the Autumn billing SDK. Capture spans for every billing operation including feature checks, usage tracking, checkout flows, product attachments, and cancellations with detailed metadata.

Visualize your billing operations with detailed span information including operation type, customer IDs, feature IDs, and billing metadata.

Installation

npm install @kubiks/otel-autumn

pnpm add @kubiks/otel-autumn

yarn add @kubiks/otel-autumn

Peer Dependencies: @opentelemetry/api >= 1.9.0, autumn-js >= 0.1.0

Quick Start

import { Autumn } from "autumn-js";
import { instrumentAutumn } from "@kubiks/otel-autumn";

const autumn = instrumentAutumn(
  new Autumn({
    secretKey: process.env.AUTUMN_SECRET_KEY!,
  }),
);

// All operations are now automatically traced
const checkResult = await autumn.check({
  customer_id: "user_123",
  feature_id: "messages",
});

await autumn.track({
  customer_id: "user_123",
  feature_id: "messages",
  value: 1,
});

instrumentAutumn wraps your Autumn client instance—no configuration changes needed. Every SDK call creates a client span with detailed billing attributes.

Traced Operations

This instrumentation wraps the core Autumn billing methods:

check

Feature access and product status checks

track

Usage event tracking

checkout

Checkout session creation

attach

Product attachment to customers

cancel

Product cancellation

Each operation creates a dedicated span with operation-specific attributes.

Span Attributes

Common Attributes (All Operations)

Attribute	Description	Example
`billing.system`	Constant value `autumn`	`autumn`
`billing.operation`	Operation type	`check`, `track`
`autumn.resource`	Resource being accessed	`features`, `products`
`autumn.target`	Full operation target	`features.check`
`autumn.customer_id`	Customer ID	`user_123`
`autumn.entity_id`	Entity ID (if applicable)	`org_456`

Check Operation

Feature Access Attributes

Attribute	Description	Example
`autumn.feature_id`	Feature being checked	`messages`
`autumn.allowed`	Whether access is allowed	`true`
`autumn.balance`	Current balance/remaining uses	`42`
`autumn.usage`	Current usage	`8`
`autumn.unlimited`	Whether usage is unlimited	`false`
`autumn.required_balance`	Required balance for operation	`1`

Product Status Attributes

Attribute	Description	Example
`autumn.product_id`	Product being checked	`pro`
`autumn.included_usage`	Included usage in plan	`50`

Track Operation

Attribute	Description	Example
`autumn.feature_id`	Feature being tracked	`messages`
`autumn.event_name`	Custom event name	`message_sent`
`autumn.value`	Usage value tracked	`1`
`autumn.event_id`	Generated event ID	`evt_123`
`autumn.idempotency_key`	Idempotency key for dedup	`msg_456`

Checkout Operation

Attribute	Description	Example
`autumn.product_id`	Product being purchased	`pro`
`autumn.product_ids`	Multiple products (comma-separated)	`pro, addon_analytics`
`autumn.checkout_url`	Stripe checkout URL	`https://checkout.stripe.com/...`
`autumn.has_prorations`	Whether prorations apply	`true`
`autumn.total_amount`	Total checkout amount	`2000` (cents)
`autumn.currency`	Currency code	`usd`
`autumn.force_checkout`	Whether to force Stripe checkout	`false`
`autumn.invoice`	Whether to create invoice	`true`

Attach Operation

Attribute	Description	Example
`autumn.product_id`	Product being attached	`pro`
`autumn.success`	Whether attachment succeeded	`true`
`autumn.checkout_url`	Checkout URL if payment needed	`https://checkout.stripe.com/...`

Cancel Operation

Attribute	Description	Example
`autumn.product_id`	Product being cancelled	`pro`
`autumn.success`	Whether cancellation succeeded	`true`

Configuration

You can optionally configure the instrumentation:

import { instrumentAutumn } from "@kubiks/otel-autumn";

const autumn = instrumentAutumn(client, {
  // Capture customer data in spans (default: false)
  captureCustomerData: true,

  // Capture product options/configuration (default: false)
  captureOptions: true,
});

By default, sensitive customer data is not captured. Enable captureCustomerData only if your observability platform is secure and compliant.

Usage Examples

Feature Access Control

const autumn = instrumentAutumn(
  new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY! }),
);

// Check if user can access a feature
const result = await autumn.check({
  customer_id: "user_123",
  feature_id: "messages",
  required_balance: 1,
});

if (result.data?.allowed) {
  // User has access
  console.log(`Remaining: ${result.data.balance}`);
}

// Check product status
const result = await autumn.check({
  customer_id: "user_123",
  product_id: "pro",
});

if (result.data?.allowed) {
  console.log("User has Pro subscription");
}

Usage Tracking

// Track feature usage
await autumn.track({
  customer_id: "user_123",
  feature_id: "messages",
  value: 1,
});

// Track with idempotency key to prevent double-counting
await autumn.track({
  customer_id: "user_123",
  feature_id: "messages",
  value: 1,
  idempotency_key: `msg_${messageId}`,
});

// Track custom event
await autumn.track({
  customer_id: "user_123",
  event_name: "video_upload",
  value: 1,
});

Checkout Flow

// Create a checkout session for a product
const result = await autumn.checkout({
  customer_id: "user_123",
  product_id: "pro",
  force_checkout: false, // Use billing portal if payment method exists
});

if (result.data?.url) {
  // Redirect to Stripe checkout
  console.log(`Checkout URL: ${result.data.url}`);
}

// Checkout with multiple products
const result = await autumn.checkout({
  customer_id: "user_123",
  product_ids: ["pro", "addon_analytics"],
});

// Always use Stripe checkout (even if payment method exists)
const result = await autumn.checkout({
  customer_id: "user_123",
  product_id: "enterprise",
  force_checkout: true,
});

Product Management

// Attach a free product
const attachResult = await autumn.attach({
  customer_id: "user_123",
  product_id: "free",
});

if (attachResult.data?.success) {
  console.log("Product attached successfully");
}

// Cancel a subscription
const cancelResult = await autumn.cancel({
  customer_id: "user_123",
  product_id: "pro",
});

if (cancelResult.data?.success) {
  console.log("Subscription cancelled");
}

Complete Integration Example

Here’s a complete example integrating Autumn with a Next.js application:

lib/autumn.ts

import { Autumn } from "autumn-js";
import { instrumentAutumn } from "@kubiks/otel-autumn";

export const autumn = instrumentAutumn(
  new Autumn({
    secretKey: process.env.AUTUMN_SECRET_KEY!,
  }),
  {
    captureCustomerData: true,
    captureOptions: true,
  }
);

app/api/features/check/route.ts

import { autumn } from "@/lib/autumn";
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const { customerId, featureId } = await request.json();

  const result = await autumn.check({
    customer_id: customerId,
    feature_id: featureId,
    required_balance: 1,
  });

  return NextResponse.json(result.data);
}

app/api/usage/track/route.ts

import { autumn } from "@/lib/autumn";
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const { customerId, featureId, value, idempotencyKey } = await request.json();

  await autumn.track({
    customer_id: customerId,
    feature_id: featureId,
    value,
    idempotency_key: idempotencyKey,
  });

  return NextResponse.json({ success: true });
}

Best Practices

Use Idempotency Keys

Always use idempotency keys when tracking usage to prevent double-counting:

await autumn.track({
  customer_id: "user_123",
  feature_id: "messages",
  value: 1,
  idempotency_key: `msg_${messageId}`,
});

Check Before Usage

Check feature access before performing operations:

const check = await autumn.check({
  customer_id: "user_123",
  feature_id: "messages",
  required_balance: 1,
});

if (!check.data?.allowed) {
  throw new Error("Insufficient balance");
}

// Proceed with operation
await sendMessage();

// Track usage
await autumn.track({
  customer_id: "user_123",
  feature_id: "messages",
  value: 1,
});

Handle Checkout Redirects

Handle both checkout URLs and direct product attachments:

const result = await autumn.checkout({
  customer_id: "user_123",
  product_id: "pro",
});

if (result.data?.url) {
  // Redirect to Stripe checkout
  return redirect(result.data.url);
} else {
  // Product attached directly (e.g., free plan)
  return redirect("/dashboard");
}

Configure Data Capture Carefully

Only enable additional data capture in secure environments:

const autumn = instrumentAutumn(client, {
  captureCustomerData: process.env.NODE_ENV === "development",
  captureOptions: true,
});

Troubleshooting

Spans Not Appearing

Make sure OpenTelemetry is properly configured in your application:

import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";

const sdk = new NodeSDK({
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

Missing Attributes

Ensure you’re using the latest version of the package:

npm update @kubiks/otel-autumn

Performance Impact

The instrumentation adds minimal overhead. If you experience issues:

Verify your OpenTelemetry exporter is configured correctly
Check if you’re using sampling to reduce data volume
Consider using batch span processors

Resources

Autumn Documentation

Learn more about Autumn billing

GitHub Repository

View source code and examples

npm Package

View package on npm

Report Issues

Found a bug? Let us know!

License

MIT

Frameworks

Vercel

OpenTelemetry Integrations

Autumn Billing

Overview

Installation

Quick Start

Traced Operations

check

track

checkout

attach

cancel

Span Attributes

Common Attributes (All Operations)

Check Operation

Track Operation

Checkout Operation

Attach Operation

Cancel Operation

Configuration

Usage Examples

Feature Access Control

Usage Tracking

Checkout Flow

Product Management

Complete Integration Example

Best Practices

Troubleshooting

Resources

Autumn Documentation

GitHub Repository

npm Package

Report Issues

License

​Overview

​Installation

​Quick Start

​Traced Operations

check

track

checkout

attach

cancel

​Span Attributes

​Common Attributes (All Operations)

​Check Operation

​Track Operation

​Checkout Operation

​Attach Operation

​Cancel Operation

​Configuration

​Usage Examples

​Feature Access Control

​Usage Tracking

​Checkout Flow

​Product Management

​Complete Integration Example

​Best Practices

​Troubleshooting

​Resources

Autumn Documentation

GitHub Repository

npm Package

Report Issues

​License

Overview

Installation

Quick Start

Traced Operations

Span Attributes

Common Attributes (All Operations)

Check Operation

Track Operation

Checkout Operation

Attach Operation

Cancel Operation

Configuration

Usage Examples

Feature Access Control

Usage Tracking

Checkout Flow

Product Management

Complete Integration Example

Best Practices

Troubleshooting

Resources

License